اکشن و فیلتر: قلاب‌های وردپرس به زبان ساده

بیشتر راهنماهای وردپرس یک جمله‌ی کلیدی دارند: «از قلاب استفاده کن». اگر نمی‌دانید قلاب چیست، این جمله مثل یک رمز است. حقیقت ساده‌تر است. وردپرس در نقطه‌های مشخصی از اجرای خود می‌ایستد و می‌پرسد «کسی چیزی برای گفتن دارد؟». هر تابعی که به آن نقطه وصل شده باشد، اجرا می‌شود. این نقطه‌ها قلاب (Hook) هستند.

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

دو نوع قلاب#

یک تصور ساده: اکشن مثل زنگ در است؛ صدا می‌کند و هر کس خواست کاری می‌کند. فیلتر مثل یک خط تولید است؛ مقدار از دست شما رد می‌شود، تغییر می‌کند و به دست بعدی می‌رسد.

نخستین اکشن#

<?php
add_action( 'wp_footer', 'demo_footer_note' );

function demo_footer_note(): void {
	echo '<p class="demo-note">' . esc_html__( 'ساخته‌شده با وردپرس', 'demo' ) . '</p>';
}

wp_footer قلاب فوتر قالب است. تابع ما همان‌جا اجرا می‌شود و یک خط چاپ می‌کند. دقت کنید که خروجی را esc_html__ گذرانده‌ایم؛ همیشه خروجی را در لحظه‌ی چاپ escape کنید.

نخستین فیلتر#

<?php
add_filter( 'the_content', 'demo_append_note' );

function demo_append_note( string $content ): string {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $content; // شرط برقرار نیست؛ مقدار اصلی را برگردان
	}
	$note = '<p><em>' . esc_html__( 'این مطلب به‌روز نگه داشته می‌شود.', 'demo' ) . '</em></p>';
	return $content . $note;
}

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

اولویت و تعداد آرگومان#

آرگومان‌های سوم و چهارم هر دو تابع ثبت، اولویت و تعداد آرگومان‌اند:

<?php
add_filter( 'the_title', 'demo_title_prefix', 20, 2 );

function demo_title_prefix( string $title, int $post_id ): string {
	if ( 'product' === get_post_type( $post_id ) ) {
		return '* ' . $title;
	}
	return $title;
}

• اولویت ۲۰: بعد از توابع با اولویت پیش‌فرض ۱۰ اجرا می‌شود.
• عدد ۲: وردپرس این قلاب را با دو مقدار صدا می‌زند (عنوان و شناسه) و ما هر دو را می‌خواهیم. اگر عدد را ننویسید، فقط اولی به تابع می‌رسد.

مستندات رسمی هر قلاب می‌گوید چند آرگومان می‌دهد؛ حدس نزنید.

چند قلاب پرکاربرد#

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

ساخت قلاب اختصاصی#

وقتی افزونه‌ی خودتان را می‌نویسید، با do_action و apply_filters به دیگران اجازه‌ی توسعه بدهید:

<?php
function demo_render_badge( int $user_id ): string {
	$label = apply_filters( 'demo_badge_label', __( 'عضو', 'demo' ), $user_id );
	do_action( 'demo_before_badge', $user_id );

	return '<span class="badge">' . esc_html( $label ) . '</span>';
}

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

برداشتن قلاب#

<?php
add_action( 'init', function () {
	remove_action( 'wp_head', 'wp_generator' );
} );

برای برداشتن، نام تابع و اولویت باید دقیقاً همان‌هایی باشد که هنگام ثبت استفاده شده است. توابع بی‌نام (closure) را به‌سادگی نمی‌شود برداشت؛ اگر قرار است برداشته شوند، تابع نام‌دار بنویسید.

اشتباه‌های رایج#

• برنگرداندن مقدار در فیلتر: نتیجه صفحه‌ی خالی یا عنوان ناپدید است.
• ثبت قلاب خیلی زود: بعضی توابع مثل is_singular پیش از بارگذاری پرس‌وجو جواب درست نمی‌دهند. برای کدهایی که به وضعیت صفحه وابسته‌اند، قلاب‌های wp یا template_redirect را به‌کار ببرید.
• echo در فیلتر: فیلتر باید مقدار را برگرداند، نه چاپ کند.
• فراموش‌کردن escape: هر چیزی را که چاپ می‌کنید در همان لحظه escape کنید.
• کد در قالب اصلی: با تعویض قالب پاک می‌شود. افزونه یا قالب فرزند بهتر است.

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

خلاصه#

• قلاب نقطه‌ای است که وردپرس صبر می‌کند تا توابع شما را اجرا کند.
• اکشن کاری انجام می‌دهد؛ فیلتر مقداری را تغییر می‌دهد و باید برگرداند.
• اولویت پیش‌فرض ۱۰ است و عدد کمتر زودتر اجرا می‌شود.
• تعداد آرگومان را مطابق مستندات همان قلاب تنظیم کنید.
• برای افزونه‌ی خودتان با do_action و apply_filters قلاب بسازید.
• خروجی را همیشه در لحظه‌ی چاپ escape کنید و کد را در افزونه یا قالب فرزند نگه دارید.