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

تابع get_term() یکی از توابع پایه‌ای وردپرس برای دریافت اطلاعات یک ترم (term) از یک taxonomy است. این تابع اطلاعات خام ترم را به‌صورت شیء WP_Term یا آرایه برمی‌گرداند و در قالب‌سازی صفحه‌ها، نمایش بایگانی‌ها، یا پردازش داده‌های مرتبط با taxonomy کاربرد فراوانی دارد. در ادامه به امضاء تابع، نمونه‌های کاربردی، نکات حرفه‌ای و روش‌های بهینه‌سازی می‌پردازیم.

امضای تابع و جدول پارامترها

مقدار بازگشتی: معمولاً یک شیء WP_Term در صورت موفقیت؛ در صورت خطا ممکن است false یا WP_Error برگردد. بنابراین همواره باید نوع مقدار بازگشتی را چک کنید.

مثال پایه — دریافت نام و لینک ترم

 $term_id = 12;
$term = get_term( $term_id, 'category' );

if ( ! is_wp_error( $term ) && $term ) {
    echo esc_html( $term->name );
    echo ' — ';
    echo esc_url( get_term_link( $term ) );
} else {
    echo 'ترم یافت نشد.';
}

توضیح: در این مثال ابتدا ترم با آی‌دی 12 از taxonomy «category» گرفته می‌شود. با استفاده از is_wp_error و بررسی وجود $term ایمن شده‌ایم. سپس نام ترم را با esc_html و لینک ترم را با get_term_link و esc_url خروجی می‌دهیم تا از لحاظ امنیتی و نمایش سالم باشد.

خروجی به‌صورت آرایه

 $term_array = get_term( 5, 'product_cat', ARRAY_A );

if ( $term_array ) {
    // دسترسی به مقادیر مانند $term_array['name'] یا $term_array['term_id']
    print_r( $term_array );
}

توضیح: با تعیین پارامتر سوم به ARRAY_A، نتیجه به‌صورت آرایه انجمنی بازمی‌گردد که برای پردازش‌های خاص یا تبدیل به JSON مناسب است.

ترکیب get_term() با get_term_meta()

 $term = get_term( $term_id, 'brand' );

if ( $term && ! is_wp_error( $term ) ) {
    $rating = get_term_meta( $term->term_id, 'brand_rating', true );
    echo sprintf( '%s — Rating: %s', esc_html( $term->name ), esc_html( $rating ) );
}

توضیح: برای دریافت متادیتای مرتبط با ترم از get_term_meta استفاده می‌کنیم. این روش معمول برای افزودن داده‌های سفارشی (مانند رتبه، آیکن یا توضیحات اضافی) است.

مدیریت خطا و تطبیق taxonomy

 $input = 34; // ممکن است از ورودی کاربر باشد
$term = get_term( $input, 'topic' );

if ( is_wp_error( $term ) ) {
    error_log( 'get_term error: ' . $term->get_error_message() );
} elseif ( ! $term ) {
    // Term not found
} else {
    // OK
}

توضیح: وقتی taxonomy نامعتبر باشد یا ترم پیدا نشود، تابع ممکن است WP_Error یا false بازگرداند. بهتر است خطاها را لاگ کنید و از assumptions جلوگیری کنید.

بهینه‌سازی، کش و نکات عملکردی

• get_term() خود از کش (object cache) وردپرس استفاده می‌کند. در لوپ‌های بزرگ بهتر است بارها آن را فراخوانی نکنید؛ در عوض ابتدا تمام شناسه‌ها را گرفته و سپس با یک حلقه از کش استفاده کنید.
• پس از به‌روزرسانی ترم با wp_update_term یا به‌روزرسانی متا، گاهی لازم است کش مرتبط را پاک کنید (wp_cache_delete) تا نسخه جدید بازتاب یابد.
• برای جستجو بر اساس slug یا نام از get_term_by() استفاده کنید. get_term() برای زمانی است که شناسه ترم را دارید یا شیء ترم موجود است.

مثال بهبود عملکرد: پیش‌بارگذاری ترم‌ها

 // فرض: یک آرایه از term_idها داریم
$term_ids = array(2, 5, 7, 12);

// پیش‌بارگذاری (یک بار فراخوانی در حلقه منطقی)
$terms = array();
foreach ( $term_ids as $id ) {
    $terms[ $id ] = get_term( $id, 'category' );
}

// سپس در خروجی از $terms استفاده می‌کنیم بدون فراخوانی مکرر
foreach ( $terms as $t ) {
    if ( $t && ! is_wp_error( $t ) ) {
        echo esc_html( $t->name );
    }
}

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

نکات حرفه‌ای و ترفندها

• همیشه خروجی متون را با توابع escaping مانند esc_html() یا esc_attr() محافظت کنید.
• هنگام کار با taxonomyهای دلخواه بررسی کنید که نام taxonomy درست است؛ mismatch بین taxonomy و term_id ممکن است منجر به خطا یا داده اشتباه شود.
• برای دریافت لیست تمام ترم‌ها از get_terms() استفاده کنید، سپس روی نتایج حلقه زده و از get_term برای جزئیات بیشتری استفاده کنید.
• اگر می‌خواهید ترم با slug یا name را جستجو کنید، از get_term_by( ‘slug’ , $slug, $taxonomy ) بهره ببرید؛ get_term برای مورد id یا شیء مناسب‌تر است.
• در محیط‌هایی با کش خارجی (مثل Redis یا Memcached)، از ابزارهای debug وردپرس برای اطمینان از کش شدن صحیح استفاده کنید.

اشکال‌زدایی رایج

• خطای “Invalid taxonomy” — معمولاً taxonomy اشتباه است یا به درستی ثبت نشده.
• دادهٔ قدیمی نمایش داده می‌شود — کش پاک نشده پس از بروزرسانی ترم.
• نتیجه false اما انتظار شیء — ممکن است id وجود نداشته باشد یا دسترسی کاربر محدود شده باشد (Capability checks).

موارد استفاده رایج

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

جمع‌بندی

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

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

ارسال