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

تابع wp_get_post_terms() یکی از توابع کاربردی وردپرس برای واکشی ترم‌های مرتبط با یک نوشته (Post) بر اساس یک یا چند تکسونومی (taxonomy) است. این تابع برای نمایش دسته‌ها، برچسب‌ها یا ترم‌های سفارشی در قالب‌ها، ویجت‌ها یا APIها بسیار مفید است. در این مقاله به صورت جامع پارامترها، نمونه‌های عملی، نکات بهینه‌سازی و تفاوت آن با توابع مشابه را بررسی می‌کنیم.

مقدمه و کاربردهای رایج

با wp_get_post_terms می‌توانید به راحتی ترم‌های یک پست را دریافت کنید و آن‌ها را نمایش دهید، لینک بزنید، یا برای فیلترینگ و ساخت UI مبتنی بر تکسونومی استفاده کنید. موارد کاربرد شامل نمایش برچسب‌ها در single.php، ساخت breadcrumb بر پایه تکسونومی، یا گزینش محصولات بر اساس دسته‌بندی در قالب فروشگاه است.

ساختار و پارامترها

تابع به شکل زیر فراخوانی می‌شود:

wp_get_post_terms( int $post_id, string|array $taxonomy, array|string $args = array() )

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

$post_id: شناسهٔ نوشته (یا object_id) که ترم‌هایش می‌خواهیم.
$taxonomy: نام تکسونومی یا آرایه‌ای از نام‌ها؛ مثل ‘category’، ‘post_tag’ یا ‘product_cat’.
$args: آرایه‌ای از آرگومان‌ها برای فیلتر، مرتب‌سازی و نوع خروجی.

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

پارامتر	توضیح
fields	نوع خروجی: ‘all’ (پیش‌فرض، اشیاء WP_Term)، ‘ids’ (آرایهٔ شناسه‌ها)، ‘names’ (فقط نام‌ها) و غیره.
orderby, order	مرتب‌سازی ترم‌ها (مثلاً orderby => ‘name’، order => ‘ASC’).
hide_empty	نمایش یا عدم نمایش ترم‌های خالی (true/false).
include_children	در صورت داشتن درختی بودن تکسونومی، شامل کردن ترم‌های فرزند.
update_term_meta_cache	کنترل به‌روزرسانی cache متادیتا در فراخوانی‌های متعدد.

مثال پایه: گرفتن و نمایش ترم‌ها

$terms = wp_get_post_terms( get_the_ID(), 'category' );

if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo esc_html( $term->name ) . ' ';
    }
}

توضیح: در این مثال، ترم‌های دسته (category) برای پست جاری با get_the_ID() گرفته می‌شوند. بررسی می‌کنیم که خروجی خالی یا خطا نباشد و سپس نام هر ترم را با esc_html چاپ می‌کنیم تا امنیت خروجی حفظ شود.

مثال: نمایش لینک ترم‌ها

$terms = wp_get_post_terms( $post_id, 'product_cat' );

if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        $url = get_term_link( $term );
        if ( ! is_wp_error( $url ) ) {
            echo '<a href="' . esc_url( $url ) . '">' . esc_html( $term->name ) . '</a> ';
        }
    }
}

توضیح: اینجا برای تکسونومی سفارشی product_cat لینک هر ترم را با get_term_link می‌گیریم و سپس با esc_url و esc_html خروجی امن تولید می‌کنیم. بررسی is_wp_error برای دریافت ایمن لینک ضروری است.

دریافت فقط نام‌ها یا آی‌دی‌ها

$names = wp_get_post_terms( $post_id, 'post_tag', array( 'fields' => 'names' ) );
// $names یک آرایه از رشته‌های نام برچسب‌ها خواهد بود

$ids = wp_get_post_terms( $post_id, 'category', array( 'fields' => 'ids' ) );
// $ids یک آرایه از term_id ها خواهد بود

توضیح: با پارامتر fields می‌توانید نوع خروجی را کم‌حجم‌تر کنید؛ مخصوصاً وقتی تنها به نام یا شناسه نیاز دارید این کار مصرف حافظه و پردازش را کاهش می‌دهد.

تفاوت wp_get_post_terms با get_the_terms و wp_get_object_terms

get_the_terms: بیشتر برای قالب‌ها متداول است و گاهی false یا WP_Error برمی‌گرداند. معمولاً ساده‌تر است اما تنظیمات کمتری دارد.
wp_get_post_terms: یک wrapper است که انعطاف بیشتری برای آرگومان‌ها و فیلدها می‌دهد و به wp_get_object_terms بستگی دارد.
wp_get_object_terms: سطح پایینی‌تر با امکانات بیشتر برای کار با چند شیء ثبت شده.

نکات بهینه‌سازی و کش

وقتی این تابع را داخل لوپ‌های بزرگ (مثلاً آرشیو با ده‌ها پست) فراخوانی می‌کنید، باید به کش و تعداد کوئری‌ها توجه کنید:

از fields مناسب استفاده کنید تا داده‌ی اضافی بارگذاری نشود.
پارامتر update_term_meta_cache را در صورت نیاز غیرفعال یا فعال کنید تا از فراخوانی‌های غیرضروری متادیتا جلوگیری شود.
برای نمایش ترم‌های بسیاری از چند پست، بهتر است ترم‌ها را یک‌بار با توابع جمعی (مثل get_terms یا wp_get_object_terms با آرایه‌ای از object_ids) بگیرید و سپس در PHP به پست‌ها نسبت دهید.

نمونه پیشرفته: دریافت ترم‌ها برای چند پست هم‌زمان

$post_ids = array( 10, 11, 12 );
$terms = wp_get_object_terms( $post_ids, 'category', array(
    'fields' => 'all',
    'orderby' => 'name'
) );

// سپس می‌توانید آرایه $terms را بر اساس object_id مرتب کنید یا در نمایش‌ها استفاده کنید

توضیح: این روش بار پایگاه‌داده را کاهش می‌دهد چون به‌جای فراخوانی wp_get_post_terms برای هر پست به‌صورت مجزا، یک کوئری واحد ترم‌ها را برای چند شناسه می‌گیرد.

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

هرگاه ترم‌ها را در خروجی HTML چاپ می‌کنید از توابع فرانت-اند وردپرس مثل esc_html و esc_url استفاده کنید.
اگر ورودی post_id از منبع خارجی می‌آید آن را به‌درستی sanitize کنید (مثلاً intval).
برای نمایش لینک‌ها همیشه get_term_link را بررسی کنید تا WP_Error تولید نکند.

جمع‌بندی و توصیه‌های عملی

wp_get_post_terms یک ابزار قدرتمند برای کار با تکسونومی‌ها در وردپرس است. با درک پارامترها و توجه به cache و امنیت می‌توانید نمایش ترم‌ها را سریع، امن و انعطاف‌پذیر پیاده‌سازی کنید. در پروژه‌های بزرگ بهینه‌سازی فراخوانی‌ها و استفاده از آرگومان‌های مناسب می‌تواند تاثیر زیادی روی سرعت بارگذاری داشته باشد.

اگر به مثال‌های سفارشی (مثلاً نمایش breadcrumb بر اساس یک تکسونومی خاص یا فیلتر پست‌ها با AJAX) نیاز دارید، می‌توانم نمونه‌های مرتبط را نیز تهیه کنم.

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

خیر

بله