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

تابع wp_update_term() در وردپرس برای به‌روزرسانی یک ترم (term) در یک تکسونومی مشخص استفاده می‌شود. هرگاه بخواهید نام، اسلاگ، توضیحات یا رابطه والد یک ترم را برنامه‌نویسی تغییر دهید، این تابع ابزار اصلی است. در ادامه به پارامترها، نحوه استفاده، نکات امنیتی، مثال‌های عملی و روش‌های بهینه‌سازی می‌پردازیم.

امکان‌ها و موارد کاربرد

• تغییر نام ترم‌ها (مثلاً دسته‌ها یا برچسب‌ها)
• اصلاح اسلاگ برای URLهای خواناتر
• به‌روزرسانی توضیحات یا تعیین والد برای ترم‌های سلسله‌ای
• به‌روزرسانی و مدیریت متادیتای ترم (با توابع متادی جداگانه)

امضای تابع و مقدار بازگشتی

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

wp_update_term( int $term_id, string $taxonomy, array|string $args = array() )

خروجی:

• در صورت موفقیت: آرایه‌ای شامل keys: term_id و term_taxonomy_id
• در صورت خطا: یک شئ WP_Error

پارامترهای مهم$args

مثال پایه: به‌روزرسانی نام و اسلاگ

$term_id = 12;
$taxonomy = 'category';
$args = array(
  'name' => 'اخبار روز',
  'slug' => 'akhbar-rooz',
  'description' => 'اخبار و مطالب روزانه'
);

$result = wp_update_term( $term_id, $taxonomy, $args );

if ( is_wp_error( $result ) ) {
  error_log( 'Update term error: ' . $result->get_error_message() );
} else {
  // $result['term_id'] و $result['term_taxonomy_id'] در دسترس هستند
}

توضیح: این کد ترم با شناسه 12 را در تکسونومی category به‌روزرسانی می‌کند. ابتدا آرایه‌ای از فیلدهای جدید (name، slug، description) تعریف شده و سپس با wp_update_term() فراخوانی می‌شود. در صورت بروز خطا باید با is_wp_error() آن را بررسی کرد.

به‌روزرسانی متادیتا (term meta)

برای ذخیره متا، بهتر است پس از موفقیت‌آمیز بودن عملیات از توابع متای ترم استفاده کنید:

$res = wp_update_term( $term_id, $taxonomy, array( 'name' => 'جدید' ) );
if ( ! is_wp_error( $res ) ) {
  update_term_meta( $res['term_id'], 'color', '#ff0000' );
}

توضیح: پس از کنترل خطا، با update_term_meta() یک کلید متا به ترم افزوده یا مقدار آن تغییر داده می‌شود. این روش مطمئن‌تر از تکیه بر پارامترهای غیررسمی است.

نکات امنیتی و اعتبارسنجی

• همیشه دسترسی کاربر را بررسی کنید، مثلاً current_user_can('manage_categories') یا capability مناسب تکسونومی.
• ورودی‌ها را سانیتایز کنید: نام با sanitize_text_field() و اسلاگ با sanitize_title().
• پیش از به‌روزرسانی وجود تکسونومی را با taxonomy_exists() بررسی کنید و از وجود ترم با get_term() مطمئن شوید.

مثال کامل با بررسی و سانیتایز

if ( ! taxonomy_exists( 'category' ) ) {
  return;
}

$term = get_term( 12, 'category' );
if ( ! $term || is_wp_error( $term ) ) {
  return;
}

if ( ! current_user_can( 'manage_categories' ) ) {
  return;
}

$new_name = sanitize_text_field( $_POST['term_name'] );
$new_slug = sanitize_title( $_POST['term_slug'] );

$check = get_term_by( 'slug', $new_slug, 'category' );
if ( $check && (int) $check->term_id !== 12 ) {
  // اسلاگ تکراری است
  wp_die( 'اسلاگ انتخابی قبلاً استفاده شده است.' );
}

$result = wp_update_term( 12, 'category', array(
  'name' => $new_name,
  'slug' => $new_slug,
) );

if ( is_wp_error( $result ) ) {
  wp_die( 'خطا در به‌روزرسانی ترم: ' . $result->get_error_message() );
}

توضیح: این مثال بررسی می‌کند که تکسونومی وجود دارد، ترم موجود است، کاربر مجوز لازم را دارد، داده‌ها سانیتایز شده و اسلاگ تکراری نیست. سپس با wp_update_term تغییرات اعمال و خطا مدیریت می‌شود.

خطاهای متداول و رفع آنها

• خطای WP_Error: ممکن است به‌خاطر نام تکراری یا مشکل دیتابیس باشد — پیام خطا را بررسی کنید.
• تداخل اسلاگ: همیشه قبل از ذخیره، اسلاگ را آزمایش کنید و از یونیک بودن آن مطمئن شوید.
• عدم نمایش تغییرات در فرانت‌اند: کش (cache) یا transient ممکن است مانع شود — پاکسازی cache و فراخوانی مجدد کش ترم توصیه می‌شود.

تفاوت wp_update_term با توابع دیگر

• wp_insert_term(): برای ایجاد ترم جدید استفاده می‌شود، نه به‌روزرسانی.
• wp_set_post_terms(): برای اختصاص ترم‌ها به یک پست مناسب است، نه تغییر خصوصیات ترم.
• update_term_meta(): برای به‌روزرسانی متادیتای ترم به کار می‌رود و مکمل wp_update_term است.

نتیجه‌گیری و بهترین روش‌ها

تابع wp_update_term ابزار قدرتمندی برای مدیریت برنامه‌نویسی ترم‌ها در وردپرس است. برای استفاده صحیح:

• همیشه ورودی‌ها را سانیتایز و مجوزها را بررسی کنید.
• خطاها را با is_wp_error مدیریت کنید و در صورت نیاز پیام قابل فهم ارائه دهید.
• برای متادیتا از update_term_meta استفاده کنید تا سازگاری بیشتر حفظ شود.
• در عملیات‌های دسته‌ای، از caching و batch processing مناسب بهره ببرید.

با رعایت نکات بالا می‌توانید به‌طور ایمن و مؤثر ترم‌ها را در تکسونومی‌های مختلف وردپرس به‌روزرسانی کنید و ساختار محتوای سایت را بهینه نگه دارید.

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

ارسال