آموزش تابع wp_insert_term() در وردپرس و کاربرد آن

تابع wp_insert_term() یکی از توابع اصلی وردپرس برای ایجاد ترم (term) در یک تاکسونومی است. این تابع به شما اجازه می‌دهد دسته‌ها، برچسب‌ها یا هر تاکسونومی دلخواه را به‌صورت برنامه‌ای (programmatically) بسازید و با مدیریت درست خطاها و پاک‌سازی ورودی‌ها، از تکرار یا ناسازگاری جلوگیری کنید.

شکل کلی و پارامترها

امضای تابع به صورت زیر است:

wp_insert_term( $term, $taxonomy, $args = array() );

که در آن:

• $term: نام ترم یا آرایه حاوی داده‌های پیچیده‌تر.
• $taxonomy: نام تاکسونومی مثل ‘category’ یا ‘post_tag’ یا تاکسونومی سفارشی.
• $args: آرایه‌ای از پارامترها مانند ‘description’, ‘slug’, ‘parent’.

پارامترهای متداول args

خروجی تابع

تابع یا آرایه‌ای متشکل از ‘term_id’ و ‘term_taxonomy_id’ بازمی‌گرداند یا در صورت خطا نمونه‌ای از WP_Error. بنابراین همیشه باید نتیجه را چک کنید.

نمونه ساده: ایجاد یک دسته جدید

$result = wp_insert_term(
  'خبرهای مهم',
  'category',
  array(
    'description' => 'دسته اخبار مهم سایت',
    'slug' => 'important-news'
  )
);

if ( is_wp_error( $result ) ) {
  error_log( 'Term creation error: ' . implode( ', ', $result->get_error_messages() ) );
} else {
  $term_id = $result['term_id'];
  // کارهای بعدی با $term_id
}

در این مثال ما یک دسته با نام “خبرهای مهم” می‌سازیم. در صورت بروز خطا آن را در لاگ می‌نویسیم و در غیر این صورت آیدی ترم را ذخیره می‌کنیم. دلیل استفاده از is_wp_error() جلوگیری از خطاهای غیرمنتظره است.

الگوهای خوب برای تولید ایمن ترم

• قبل از ایجاد، با term_exists() بررسی کنید تا از تکراری بودن جلوگیری شود.
• ورودی‌ها را با sanitize_text_field() یا sanitize_title() پاک کنید.
• بعد از ایجاد، در صورت نیاز از add_term_meta() یا update_term_meta() برای ذخیره متادیتا استفاده کنید.
• همیشه نتیجه تابع را با is_wp_error() چک کنید.

نمونه بهینه: چک تکرار، سانیتایز و افزودن متا

$term_name = sanitize_text_field( 'رابطه‌ها' );
$taxonomy = 'genre';

// بررسی وجود ترم
$existing = term_exists( $term_name, $taxonomy );
if ( $existing === 0 || $existing === null ) {
  $result = wp_insert_term(
    $term_name,
    $taxonomy,
    array(
      'description' => sanitize_text_field( 'ژانرهای مربوط به محتوای سایت' ),
      'slug' => sanitize_title( $term_name )
    )
  );

  if ( is_wp_error( $result ) ) {
    error_log( 'wp_insert_term error: ' . implode( ', ', $result->get_error_messages() ) );
  } else {
    $term_id = $result['term_id'];
    // افزودن متادیتا به ترم
    add_term_meta( $term_id, 'featured', '1', true );
  }
} else {
  // ترم قبلاً وجود دارد؛ می‌توانید آیدی را بگیرید
  $term_id = is_array( $existing ) ? $existing['term_id'] : $existing;
}

در این کد ابتدا نام ترم را سانیتایز می‌کنیم، سپس با term_exists() از وجود آن مطلع می‌شویم. در صورت عدم وجود، ترم را می‌سازیم و متا اضافه می‌کنیم. استفاده از add_term_meta() به ما امکان ذخیره اطلاعات اضافی مرتبط با ترم را می‌دهد.

موارد استفاده عملی

• ایجاد دسته‌ها یا برچسب‌های پیش‌فرض هنگام فعال‌سازی افزونه یا قالب.
• درج خودکار ترم‌ها هنگام ایمپورت محتوا یا مهاجرت از سیستم دیگر.
• ساخت تاکسونومی‌های سفارشی و افزودن ترم‌های پایه برای سازمان‌دهی محتوا.
• ایجاد رابط مدیریت برنامه‌ای برای تولید مجموعه‌ای از برچسب‌ها یا دسته‌ها برای محصولات، پادکست‌ها و غیره.

مثال: افزودن ترم‌ها هنگام فعال‌سازی افزونه

function myplugin_create_default_terms() {
  $terms = array( 'آموزش', 'خبر', 'تحلیل' );
  foreach ( $terms as $t ) {
    if ( ! term_exists( $t, 'post_tag' ) ) {
      wp_insert_term( $t, 'post_tag' );
    }
  }
}
register_activation_hook( __FILE__, 'myplugin_create_default_terms' );

این الگو هنگام فعال‌سازی افزونه سه برچسب پیش‌فرض برای پست‌ها اضافه می‌کند. توجه داشته باشید که استفاده از هوک فعال‌سازی مناسب است چون نیازی به اجرا در هر بار لود سایت نیست.

خطاها و نکات حرفه‌ای

• اگر نامک (slug) تکراری شود، وردپرس آن را تعدیل می‌کند. ولی بهتر است قبل از ایجاد از تناسب slug با sanitize_title() و بررسی وجود آن اطمینان حاصل کنید.
• برای تاکسونومی‌های سلسله‌ای، مقدار parent را با آیدی ترم والد به عدد صحیح تبدیل کنید تا از ارور جلوگیری شود.
• در محیط‌هایی با ترافیک بالا و فرآیندهای موازی، از قفل منطقی یا بررسی مجدد بعد از خطا برای جلوگیری از تکرارهای همزمان بهره ببرید.

خلاصه و نتیجه‌گیری

تابع wp_insert_term() ابزار بسیار کاربردی و پایه‌ای برای مدیریت برنامه‌ای تاکسونومی‌ها در وردپرس است. با رعایت نکات ایمنی مانند پاک‌سازی ورودی‌ها، بررسی وجود قبلی ترم و مدیریت خطاها، می‌توانید از این تابع برای ایجاد دسته‌ها، برچسب‌ها یا ترم‌های سفارشی به‌صورتی قابل‌اعتماد استفاده کنید. همچنین ترکیب آن با add_term_meta()، term_exists() و هوک‌های مناسب، امکان ساخت سازوکارهای پیشرفته مدیریت محتوا را فراهم می‌کند.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال