تابع wp_set_post_terms در وردپرس

تابع wp_set_post_terms() یکی از توابع کاربردی وردپرس برای اختصاص یا به‌روزرسانی ترم‌ها (terms) به یک پست است. این تابع امکان تنظیم دسته‌بندی‌ها (taxonomies) مانند category، post_tag یا هر taxonomy سفارشی را به‌صورت برنامه‌ای فراهم می‌کند. در این مقاله به شکل دقیق و عملی نحوه استفاده، پارامترها، مثال‌ها و نکات بهینه‌سازی را بررسی می‌کنیم.

چرا از wp_set_post_terms استفاده کنیم؟

اتوماتیک‌سازی برچسب‌گذاری و دسته‌بندی هنگام ایجاد یا به‌روزرسانی پست‌ها.
همگام‌سازی داده‌ها از منابع خارجی یا فرم‌های سفارشی.
مدیریت ترم‌ها در bulk operations (به‌روزرسانی دسته‌ای).

امضای تابع و پارامترها

پارامتر	توضیح
int $post_id	آی‌دی پستی که می‌خواهیم ترم‌ها برای آن تنظیم شود.
array\|string $terms	آرایه یا رشته‌ای از ترم‌ها (IDs, slugs یا names).
string $taxonomy	نام taxonomy مثل ‘category’ یا ‘post_tag’ یا taxonomy سفارشی.
bool $append (اختیاری)	اگر true باشد، ترم‌ها اضافه می‌شوند؛ در غیر این صورت ترم‌های قبلی جایگزین می‌شوند. پیش‌فرض false.

مثال پایه — اختصاص دسته‌بندی‌ها با آیدی

wp_set_post_terms( $post_id, array( 5, 9 ), 'category' );

در این مثال، دسته‌هایی با آیدی 5 و 9 به پست مشخص شده اختصاص داده می‌شوند و تمام دسته‌های قبلی جایگزین می‌گردند. اگر بخواهید ترم‌های جدید را به ترم‌های قبلی اضافه کنید از آرگومان append برابر true استفاده کنید.

مثال افزودن ترم بدون حذف ترم‌های قبلی

wp_set_post_terms( $post_id, array( 'laravel', 'php' ), 'post_tag', true );

در اینجا برچسب‌های ‘laravel’ و ‘php’ به پست اضافه می‌شوند. توجه کنید که اگر این برچسب‌ها وجود نداشته باشند، وردپرس آن‌ها را ایجاد می‌کند. تنظیم append=true باعث می‌شود ترم‌های موجود حذف نشوند و فقط ترم‌های جدید افزوده شوند.

استفاده در هوک save_post — مثال عملی

function myplugin_set_terms_on_save( $post_id ) {
    // بررسی امنیت و جلوگیری از اجرا در revisions یا autosave
    if ( defined('DOING_AUTOSAVE') && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;

    // تنظیم یک taxonomy سفارشی به‌صورت برنامه‌ای
    $terms = array( 'news', 'announcements' );
    wp_set_post_terms( $post_id, $terms, 'news_taxonomy' );
}
add_action( 'save_post', 'myplugin_set_terms_on_save' );

این کد هنگام ذخیره پست، ترم‌های مشخص شده را به taxonomy سفارشی ‘news_taxonomy’ اختصاص می‌دهد. دقت کنید که چک‌های امنیتی مانند DOING_AUTOSAVE و current_user_can الزامی هستند تا از رفتارهای ناخواسته جلوگیری شود.

ایجاد ترم‌ها قبل از اختصاص (روش امن)

$desired = array( 'fiction', 'non-fiction' );
$ids = array();

foreach ( $desired as $name ) {
    $term = term_exists( $name, 'genre' );
    if ( $term === 0 || $term === null ) {
        $created = wp_create_term( $name, 'genre' );
        if ( ! is_wp_error( $created ) ) {
            $ids[] = $created['term_id'];
        }
    } else {
        $ids[] = is_array( $term ) ? $term['term_id'] : $term;
    }
}

wp_set_post_terms( $post_id, $ids, 'genre' );

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

مقایسه با توابع مشابه

wp_set_object_terms(): پایه‌ای‌ترین تابع که برای انواع objectها (پست، لینک و …) کار می‌کند؛ wp_set_post_terms wrapper ای ساده‌تر برای پست‌ها است.
wp_set_post_categories(): فقط برای دسته‌ها (category) با پارامترهای خاصی استفاده می‌شود و به‌صورت خلاصه‌تر کار می‌کند.

نکات حرفه‌ای و بهترین شیوه‌ها

همیشه قبل از اعمال تغییر در hooks مانند save_post از چک‌های autosave و capability استفاده کنید تا چرخه بی‌نهایت یا تغییرات ناخواسته رخ ندهد.
برای عملیات دسته‌ای (bulk) از transactions یا batching استفاده کنید و درخواست‌های متعدد به دیتابیس را کاهش دهید.
اگر قرار است نام‌ها را به‌عنوان ورودی بگیرید، بهتر است ابتدا آن‌ها را sanitize کرده و از term_exists استفاده کنید تا duplicate یا خطا ایجاد نشود.
برای جلوگیری از تغییرات غیرمجاز، دسترسی‌ها (capabilities) را بررسی و مجوزها را مدیریت کنید.
در سایت‌های بزرگ با تعداد ترم زیاد، استفاده مکرر از توابعی که درخواست‌های DB ایجاد می‌کنند می‌تواند هزینه‌بر باشد؛ کشینگ و تهیه لیست ترم‌ها قبلی می‌تواند مفید باشد.

خطاهای رایج و رفع آن‌ها

ترم‌های ناپدید می‌شوند: ممکن است append=false استفاده شده باشد — مقدار append را بررسی کنید.
ایجاد ترم با نام تکراری یا نامعتبر: قبل از ایجاد، نام را sanitize کنید و از term_exists استفاده کنید.
عدم اعمال تغییرات در save_post: ممکن است hook recursion ایجاد شده باشد؛ هنگام تغییر ترم در save_post از remove_action/add_action برای جلوگیری از لوپ استفاده کنید.

جمع‌بندی

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

آیا این مطلب برای شما مفید بود ؟

خیر

بله