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

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

تابع `add_filter()` چیست؟

در وردپرس، «فیلترها» (Filters) به شما اجازه می‌دهند که داده‌ها را قبل از نمایش به کاربر یا قبل از ذخیره در پایگاه‌داده، تغییر دهید. تابع add_filter() برای اتصال یک تابع سفارشی به یک فیلتر خاص استفاده می‌شود تا بتوانید خروجی آن فیلتر را تغییر دهید.

ساختار کلی تابع

add_filter( $hook_name, $callback, $priority, $accepted_args );

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

پارامتر	توضیح
`$hook_name`	نام فیلتر یا هوک مورد نظر (مثلاً `the_content` یا `excerpt_length`).
`$callback`	نام تابعی که باید هنگام اجرای فیلتر فراخوانی شود.
`$priority`	عدد تعیین‌کننده ترتیب اجرای فیلترها (پیش‌فرض: 10).
`$accepted_args`	تعداد آرگومان‌هایی که تابع شما می‌پذیرد (پیش‌فرض: 1).

نمونه کد ساده از تابع `add_filter()`


function modify_excerpt_length( $length ) {
    return 30; // تعداد کلمات خلاصه نوشته
}
add_filter( 'excerpt_length', 'modify_excerpt_length' );

در این مثال، ما طول خلاصه نوشته (excerpt) را با استفاده از فیلتر excerpt_length تغییر داده‌ایم تا همیشه ۳۰ کلمه باشد. تابع modify_excerpt_length مقدار جدید را بازمی‌گرداند و وردپرس از آن به‌جای مقدار پیش‌فرض استفاده می‌کند.

نحوه عملکرد فیلترها در وردپرس

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

مثال پیشرفته‌تر با چند فیلتر


function add_custom_prefix( $title ) {
    return '⭐ ' . $title;
}
function add_custom_suffix( $title ) {
    return $title . ' 🔥';
}

add_filter( 'the_title', 'add_custom_prefix', 5 );
add_filter( 'the_title', 'add_custom_suffix', 15 );

در این مثال دو فیلتر به the_title متصل شده‌اند. ابتدا تابع add_custom_prefix با اولویت ۵ اجرا می‌شود و پیشوند اضافه می‌کند، سپس تابع دوم add_custom_suffix با اولویت ۱۵ اجرا شده و پسوند را اضافه می‌کند.

تفاوت `add_action()` و `add_filter()`

ویژگی	`add_action()`	`add_filter()`
هدف اصلی	اجرای یک تابع در یک نقطه خاص	تغییر یا فیلتر کردن داده‌ها
خروجی	هیچ خروجی بازگردانده نمی‌شود	باید مقدار جدید بازگردانده شود
مثال	`add_action('init', 'my_init_function');`	`add_filter('the_content', 'my_content_filter');`

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

همیشه در انتهای تابع فیلتر، مقدار تغییر یافته را بازگردانید، نه اینکه چاپ کنید.
از نام‌گذاری توابع واضح مانند filter_the_content_custom استفاده کنید تا درک کد راحت‌تر شود.
اگر چند فیلتر روی یک هوک اعمال می‌کنید، ترتیب اجرای آن‌ها را با پارامتر $priority تنظیم کنید.
برای حذف یک فیلتر، می‌توانید از تابع remove_filter() استفاده کنید.

حذف فیلتر اضافه‌شده


remove_filter( 'the_title', 'add_custom_suffix', 15 );

در این مثال، فیلتر add_custom_suffix از هوک the_title حذف شده است و دیگر هنگام نمایش عنوان‌ها اعمال نخواهد شد.

کاربردهای پرکاربرد تابع `add_filter()`

تغییر محتوای نوشته‌ها: فیلتر the_content برای تغییر محتوای پست‌ها قبل از نمایش.
اصلاح عنوان‌ها: فیلتر the_title برای افزودن پسوند یا پیشوند به عناوین.
سفارشی‌سازی خلاصه‌ها: فیلتر excerpt_length یا excerpt_more برای کنترل نمایش خلاصه‌ها.
تغییر ایمیل‌ها: فیلتر wp_mail_from برای تغییر آدرس فرستنده ایمیل‌ها.

نمونه عملی: تغییر متن ادامه مطلب


function custom_excerpt_more( $more ) {
    return '... <a href="' . get_permalink() . '">ادامه مطلب</a>';
}
add_filter( 'excerpt_more', 'custom_excerpt_more' );

در این مثال، لینک “ادامه مطلب” به انتهای خلاصه نوشته‌ها اضافه می‌شود. این روش یکی از کاربردهای محبوب در قالب‌های وردپرس است.

دیباگ و خطایابی در فیلترها

در زمان توسعه، ممکن است بخواهید بررسی کنید که کدام فیلترها روی یک هوک اعمال شده‌اند. برای این کار می‌توانید از تابع has_filter() استفاده کنید.


if ( has_filter( 'the_content', 'custom_content_filter' ) ) {
    echo 'فیلتر فعال است';
}

تابع has_filter() بررسی می‌کند که آیا تابع مورد نظر روی هوک مشخصی متصل است یا خیر. این کار برای عیب‌یابی عملکرد افزونه‌ها و قالب‌ها بسیار مفید است.

جمع‌بندی نکات کلیدی

add_filter() برای تغییر داده‌ها قبل از خروجی در وردپرس استفاده می‌شود.
هر فیلتر باید مقدار بازگشتی مشخصی داشته باشد.
می‌توانید چندین فیلتر برای یک هوک تعریف کنید.
برای حذف فیلتر از remove_filter() استفاده کنید.
برای دیباگ از has_filter() کمک بگیرید.

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

خیر

بله