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

در توسعه قالب‌ها یا افزونه‌های وردپرس، معمولاً نیاز داریم تا دسته‌بندی‌های متعلق به یک نوشته را بازیابی کنیم. تابع «get_the_category()» یکی از ابزارهای کاربردی این کار است که در این مقاله به صورت کامل آن را از منظر مفهومی، منطقی، و بهترین شیوه‌ها بررسی می‌کنیم.

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

تابع get_the_category() دسته‌بندی‌های (دسته‌های عمومی «category») یک نوشته را بازمی‌گرداند.

دید کلی:

• پارامتر ورودی: شناسه نوشته (post ID) که اختیاری است. اگر وارد نشود، نوشته جاری (درون Loop) در نظر گرفته می‌شود.
• خروجی: آرایه‌ای از اشیاء WP_Term که نشان‌دهنده دسته‌بندی‌های مرتبط با آن نوشته هستند.
• نکته مهم: این تابع فقط برای تاکسونومی “category” یعنی دسته‌بندی‌های پیش‌فرض وردپرس است؛ اگر از تاکسونومی سفارشی استفاده می‌کنید باید از تابع دیگر مانند get_the_terms() بهره بگیرید.

پارامترها، ساختار و خروجی

پارامترها

تابع به شکل زیر نگاشته شده است:

get_the_category( int $post_id = false )

توضیحات:

• $post_id: شناسه نوشته (عدد صحیح). اگر مقدار false باشد (یا پارامتر حذف شود)، تابع تلاش می‌کند از نوشته جاری در Loop استفاده کند.

خروجی

این تابع یک آرایه (ممکن است خالی) از اشیاء WP_Term بازمی‌گرداند. هر شیء شامل اطلاعاتی مانند term_id، name، slug، parent و … است.

مثال ساختار خروجی:

Array
(
  [0] => WP_Term Object
    (
      [term_id] => 7
      [name] => Codex
      [slug] => codex
      [taxonomy] => category
      [parent] => 3
      [count] => 17
      // …
    )
  [1] => WP_Term Object
    (
      [term_id] => 4
      [name] => Usefulness
      [slug] => usefulness
      [parent] => 3
      [count] => 7
      // …
    )
)

(برگرفته از مستندات)

مثال‌های کاربردی همراه با توضیح

۱. گرفتن نام اولین دسته‌بندی

$categories = get_the_category();
if ( ! empty( $categories ) ) {
    echo esc_html( $categories[0]->name );
}

توضیح: ابتدا تابع اجرا می‌شود و اگر آرایه خالی نباشد، نام اولین دسته را با استفاده از property name چاپ می‌کنیم. تابع esc_html برای محافظت خروجی استفاده شده است.

۲. نمایش نام و لینک همه دسته‌بندی‌ها

$categories = get_the_category();
if ( ! empty( $categories ) ) {
    foreach ( $categories as $category ) {
        echo 'term_id ) ) . '">';
        echo esc_html( $category->name );
        echo ' ';
    }
}

توضیح: در هر دور حلقه، لینک صفحه دسته با get_category_link ساخته شده و نام دسته در لینک نمایش داده می‌شود. این روش بسیار رایج برای نمایش “دسته‌های متعلق به نوشته” است.

۳. استفاده خارج از Loop (بیرون از حلقه اصلی وردپرس)

global $post;
$categories = get_the_category( $post->ID );
if ( ! empty( $categories ) ) {
    // روند مشابه
}

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

منطق درونی و نکات فنی

در مستندات رسمی تابع چنین آمده است:

function get_the_category( $post_id = false ) {
    $categories = get_the_terms( $post_id, 'category' );
    if ( ! $categories || is_wp_error( $categories ) ) {
        $categories = array();
    }
    $categories = array_values( $categories );
    foreach ( array_keys( $categories ) as $key ) {
        _make_cat_compat( $categories[ $key ] );
    }
    return apply_filters( 'get_the_categories', $categories, $post_id );
}

در این کد توجه کنید که:

• ابتدا با تابع get_the_terms نوشته و تاکسونومی “category” را دریافت می‌کند.
• اگر نتیجه خالی باشد یا خطا باشد، آرایه خالی برگردانده می‌شود.
• تابع _make_cat_compat برای سازگاری با نسخه‌های قدیمی‌تر وردپرس استفاده می‌شود.
• در پایان یک فیلتر «get_the_categories» اجرا می‌شود تا توسعه‌دهندگان امکان تغییر خروجی را داشته باشند.

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

• همیشه خروجی را بررسی کنید: آرایه ممکن است خالی باشد؛ بنابراین قبل از دسترسی به اندیس [0] یا سایر اندیس‌ها حتماً empty یا isset چک شود.
• فرار داده‌ها (Escaping): هنگام چاپ مقادیر خروجی حتماً از توابع esc_html، esc_url و … استفاده کنید تا امنیت قالب حفظ شود.
• توجه به تاکسونومی‌ها: اگر از یک پست‌تایپ‌ یا تاکسونومی سفارشی استفاده کرده‌اید، نباید از get_the_category استفاده کنید بلکه از get_the_terms استفاده نمایید. مستندات به این نکته تأکید دارند.
• استفاده در داخل یا خارج Loop: اگر درون Loop باشید، می‌توانید بدون پارامتر از تابع استفاده کنید. اگر خارج باشید، لازم است شناسه نوشته را بدهید.
• نمایش لینک‌ها و ساختار دلخواه: می‌توانید با حلقه و تابع get_category_link خروجی لینک‌دار تولید کنید، یا با implode و wp_list_pluck خروجی به صورت جداشده با کاما بسازید.

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

خطا‌ها و نکاتی که ممکن است به اشتباه منجر شوند

• if تابع خروجی آرایه خالی بازگرداند: ممکن است نوشته متعلق به هیچ دسته‌ای نباشد یا حلقه مناسب نباشد. در یک سؤال در StackOverflow، کاربر گزارش داد که پس از به‌روزرسانی وردپرس، تابع خالی برگردانده است.
• استفاده نادرست در تاکسونومی سفارشی: تابع فقط برای “category” است، بنابراین اگر از یک custom taxonomy استفاده شده، خروجی خالی خواهد بود یا ممکن است داده اشتباه بازگردد.
• عدم فرار داده: اگر از خروجی بدون sanitize استفاده شود، ممکن است آسیب‌پذیری XSS به وجود آید.

نمونه کاربرد پیشرفته (با بهبود)

فرض کنید می‌خواهید لینک اولین دسته‌بندی را بدون نمایش دسته‌های دیگر ایجاد کنید و اگر دسته‌ای وجود نداشت، به دسته “بدون دسته” هدایت کنید:

$categories = get_the_category( get_the_ID() );
if ( ! empty( $categories ) ) {
    // گرفتن اولین دسته
    $first_cat = $categories[0];
    echo 'term_id ) ) . '">';
    echo esc_html( $first_cat->name );
    echo '';
} else {
    // حالت fallback
    echo '' . esc_html__( 'بدون دسته‌بندی', 'textdomain' ) . '';
}

توضیح: در این کد، ابتدا آرایه دریافت می‌شود، اگر خالی نبود اولین عنصر استخراج می‌شود، سپس لینک آن با get_category_link گرفته می‌شود و خروجی چاپ می‌گردد. اگر خالی بود، یک پیام “بدون دسته‌بندی” نمایش داده می‌شود.

بهینه‌سازی برای سئو و تجربه کاربری

نمایش دسته‌بندی‌ها در قالب می‌تواند تاثیر مثبتی روی سئو و تجربه کاربری داشته باشد. با این روش‌ها:

• نمایش لینک‌های دسته‌ها برای کاربران باعث می‌شود که آن‌ها بتوانند به راحتی سایر مطالب در آن دسته را پیدا کنند.
• استفاده از این تابع در بخش <head> یا breadcrumb (مسیر حرکت کاربران) به موتورهای جستجو کمک می‌کند تا ساختار محتوا را بهتر درک کنند.
• با فرار داده‌ها و رعایت اصول امنیتی، اطمینان می‌دهید که قالب شما از نظر عملکرد و امنیت در سطح خوبی است.

جمع‌بندی

تابع get_the_category() یک ابزار ساده ولی بسیار کاربردی در توسعه قالب وردپرس است که با استفاده از آن می‌توان دسته‌بندی‌های نوشته را بازیابی و به نحو دلخواه نمایش داد. آشنایی با پارامترها، خروجی، و بهترین شیوه‌ها باعث می‌شود قالب و افزونهٔ شما از نظر ساختار و عملکرد قوی‌تر شود.

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

ارسال