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

تابع wp_delete_term() یکی از توابع پایه‌ای وردپرس برای حذف اصطلاحات (terms) در یک taxonomy است. اصطلاح می‌تواند دسته‌بندی (category)، برچسب (tag) یا هر taxonomy سفارشی باشد. در این مقاله به صورت کامل عملکرد، ورودی‌ها، خروجی، نکات فنی و مثال‌های عملی با کد را بررسی می‌کنیم تا بتوانید به‌صورت ایمن و مؤثر از این تابع در پلاگین‌ها یا قالب‌های خود استفاده کنید.

تعریف کلی و هدف تابع

تابع wp_delete_term() یک term مشخص در یک taxonomy مشخص را از جدول‌های مربوط به taxonomy در دیتابیس وردپرس حذف می‌کند. حذف شامل برداشتن ردیف‌های مرتبط در جداول wp_terms، wp_term_taxonomy و پاکسازی ارتباطات در wp_term_relationships است.

امضای تابع

امضای تابع به شکل زیر است:

wp_delete_term( $term, $taxonomy, $args = array() )

توضیح پارامترها:

• $term: شناسه عددی term یا slug (معمولاً ID عددی توصیه می‌شود).
• $taxonomy: نام taxonomy به‌صورت رشته (مثلاً ‘category’ یا ‘post_tag’).
• $args: آرایه‌ای از تنظیمات اختیاری (بعضی نسخه‌ها آن را پشتیبانی می‌کنند؛ در بسیاری موارد می‌توانید خالی بگذارید).

مقدار بازگشتی

در اجراهای موفق تابع معمولاً مقدار true یا شناسه/اطلاعات حذف‌شده باز می‌گردد و در صورت خطا یک شیء WP_Error برگشت داده می‌شود. بنابراین همواره باید خروجی را با is_wp_error بررسی کنید تا از برخورد برنامه با خطا جلوگیری کنید.

مکانیزم داخلی (خلاصه)

• بررسی وجود term در taxonomy از طریق توابع داخلی.
• حذف ردیف از wp_term_taxonomy و سپس در صورت لزوم حذف wpis در wp_terms (در صورتی که آن term در هیچ taxonomy دیگری استفاده نشده باشد).
• پاکسازی روابط با پست‌ها در wp_term_relationships برای آن term_taxonomy_id.
• اجرا کردن اکشن‌ها (hooks) مثل do_action(‘delete_term’, …) و do_action(“delete_{$taxonomy}”, …)، تا پلاگین‌ها و قالب‌ها بتوانند به حذف واکنش نشان دهند.

نکات مهم و بهترین روش‌ها

• wp_delete_term خودش بررسی‌های سطح دسترسی کاربر (capabilities) را انجام نمی‌دهد. اگر در بک‌اند یا پلاگین با دسترسی کاربر سروکار دارید، قبل از فراخوانی تابع از قابلیت‌ها مثل current_user_can(‘delete_term’) یا بررسی nonce استفاده کنید.
• در صورتی که term دارای children (در taxonomyهای hierarchical) باشد، معمولاً حذف parent باعث تغییر وضعیت children می‌شود؛ رفتار دقیق ممکن است بسته به نسخه وردپرس متفاوت باشد، بنابراین قبل از حذف در محیط تولید تست کنید. اگر می‌خواهید کودکان را هم حذف یا مجدداً اختصاص دهید، آن‌ها را صریحاً مدیریت کنید.
• از آنجا که وردپرس از نسخه‌های جدید دارای term meta است، اگر داده‌های متا به صورت جداگانه ذخیره کرده‌اید، ممکن است بخواهید قبل یا پس از حذف، متاها را هم پاکسازی کنید (مثلاً با delete_term_meta()).
• همواره خروجی را با is_wp_error چک کنید و لاگ یا پیغام کاربر را مناسب تنظیم نمایید.

مثال‌های کاربردی

مثال ساده: حذف یک دسته با شناسه

$term_id = 123;
$result = wp_delete_term( $term_id, 'category' );
if ( is_wp_error( $result ) ) {
    error_log( 'Term deletion error: ' . $result->get_error_message() );
} else {
    // حذف موفق
}

توضیح: در این مثال ابتدا شناسه دسته (123) را به تابع می‌دهیم. سپس خروجی را با is_wp_error بررسی می‌کنیم تا در صورت خطا پیام مربوطه را در لاگ ثبت کنیم. اگر خطایی وجود نداشته باشد، عملیات حذف موفقیت‌آمیز بوده است.

مثال: حذف تمام تگ‌های بدون پست (Unused tags)

// گرفتن شناسه تمام تگ‌ها (بررسی می‌کنیم که empty بودن مورد نظر است)
$unused_tags = get_terms( array(
    'taxonomy'   => 'post_tag',
    'hide_empty' => true, // hide_empty=true برای گرفتن تگ‌های استفاده‌شده؛ برای عوض کردن لاجیک می‌توان false کرد و سپس چک کرد count==0
    'fields'     => 'ids',
) );

// اگر بخواهیم تگ‌هایی که count == 0 هستند حذف شوند:
$all_tags = get_terms( array(
    'taxonomy'   => 'post_tag',
    'hide_empty' => false,
    'fields'     => 'ids',
) );

foreach ( $all_tags as $tag_id ) {
    $tag = get_term( $tag_id, 'post_tag' );
    if ( is_wp_error( $tag ) ) {
        continue;
    }
    if ( intval( $tag->count ) === 0 ) {
        $res = wp_delete_term( $tag_id, 'post_tag' );
        if ( is_wp_error( $res ) ) {
            error_log( 'Could not delete tag ' . $tag_id . ': ' . $res->get_error_message() );
        }
    }
}

توضیح: این مثال ابتدا تمام تگ‌ها را می‌گیرد و سپس آن‌هایی که مقدار count برابر صفر دارند (به اصطلاح unused) را با wp_delete_term حذف می‌کند. قبل از حذف حتماً خروجی و خطاها بررسی شده و ثبت می‌شوند تا حذف ناخواسته رخ ندهد.

مثال: حذف امن از داخل صفحه ادمین (با بررسی capability و nonce)

if ( isset( $_POST['delete_term_id'] ) && check_admin_referer( 'delete_term_action', 'delete_term_nonce' ) ) {
    $term_id = intval( $_POST['delete_term_id'] );
    if ( current_user_can( 'manage_categories' ) ) {
        $result = wp_delete_term( $term_id, 'category' );
        if ( is_wp_error( $result ) ) {
            wp_die( 'خطا در حذف: ' . esc_html( $result->get_error_message() ) );
        } else {
            wp_redirect( admin_url( 'edit-tags.php?taxonomy=category&deleted=1' ) );
            exit;
        }
    } else {
        wp_die( 'شما دسترسی لازم را ندارید.' );
    }
}

توضیح: در محیط ادمین باید هم nonce و هم capability چک شوند تا حذف تنها توسط کاربران مجاز انجام شود. مثال بالا این دو بررسی را انجام داده و در صورت موفقیت به صفحه مناسب redirect می‌کند.

هوک‌ها و توسعه‌پذیری

در زمان حذف، وردپرس چندین اکشن فراخوانی می‌کند که پلاگین‌ها می‌توانند برای پاکسازی مربوطه یا لاگینگ از آن‌ها استفاده کنند، از جمله:

• do_action(‘delete_term’, $term, $taxonomy, $deleted_term_taxonomy_id)
• do_action(“delete_{$taxonomy}”, …)

اگر نیاز دارید هنگام حذف یک term، متای مرتبط را خودکار پاک کنید یا عملیات دیگری انجام شود، بهتر است به این اکشن‌ها متصل شوید و کار خود را انجام دهید.

نکات پایانی و هشدارها

• عمل حذف غیرقابل بازگشت است مگر اینکه بک‌آپ داشته باشید؛ پیش از اجرا در محیط تولید احتیاط کنید.
• اگر می‌خواهید پست‌های مرتبط با term حذف یا مجدداً اختصاص داده شوند، این کار به صورت صریح باید انجام شود؛ wp_delete_term تنها روابط term را پاک می‌کند و پست‌ها را حذف نمی‌کند.
• قبل از اجرای دسته‌ای حذف، حتماً تست و نمایش پیش‌نمایش برای مدیر سیستم فراهم کنید.

با رعایت نکات امنیتی، بررسی خطاها و آگاهی از رفتارهای مرتبط با children و term meta، wp_delete_term ابزاری قدرتمند برای مدیریت برنامه‌نویسی taxonomy در وردپرس است.

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

ارسال