هوک‌های وردپرس به زبان ساده: اکشن، فیلتر و ۲۰ مثال واقعی بدون افزونه

هوک‌ها راه رسمی تغییر رفتار وردپرس بدون دست زدن به فایل‌های هسته، قالب یا افزونه‌های دیگران هستند. وردپرس در صدها نقطه از اجرا «صدا می‌زند» و شما با یک تابع به آن نقطه وصل می‌شوید؛ یا کاری انجام می‌دهید (اکشن) یا مقداری را تغییر می‌دهید (فیلتر). این راهنما مفهوم را با زبان ساده و تصویر توضیح می‌دهد، چهار پارامتر add_action را که بیشتر خطاها از آن‌جا می‌آید باز می‌کند و بیست مثال واقعی و آماده‌ی کپی ارائه می‌دهد که جای چندین افزونه را می‌گیرند. در پایان یاد می‌گیرید هوک افزونه‌های دیگر را حذف کنید و برای افزونه‌ی خودتان هوک بسازید.

آنچه در این آموزش یاد می‌گیرید

• تفاوت اکشن و فیلتر و اینکه چرا فیلتر بدون return سایت را خراب می‌کند

• چهار پارامتر add_action و add_filter: نام، تابع، اولویت و تعداد آرگومان

• جای درست کد: چرا افزونه‌ی mu بهتر از functions.php است

• ترتیب اجرای هوک‌ها در یک بازدید و اینکه هر کار را روی کدام هوک بگذارید

• ۲۰ مثال واقعی برای محتوا، امنیت، ورود کاربران، پیشخوان، ووکامرس، کوئری و کرون

• حذف یا تغییر هوک‌های افزونه‌های دیگر با اولویت درست

• ساخت هوک برای افزونه‌ی خودتان با do_action و apply_filters

هوک چیست و چرا وردپرس روی آن ساخته شده

تصور کنید وردپرس هنگام نمایش هر نوشته می‌گوید: «این متن نوشته است، کسی می‌خواهد قبل از نمایش تغییرش دهد؟» این جمله یک فیلتر به نام the_content است. افزونه‌ی سئو، افزونه‌ی اشتراک‌گذاری، خود وردپرس برای تبدیل خطوط به پاراگراف و کد شما همه به همین نقطه وصل می‌شوند، هر کدام متن را می‌گیرند، تغییر می‌دهند و به نفر بعدی می‌دهند. به همین شکل وقتی نوشته‌ای منتشر می‌شود وردپرس می‌گوید «نوشته منتشر شد» و هر کسی که بخواهد ایمیل بفرستد یا کش را پاک کند به آن گوش می‌دهد؛ این یک اکشن است.

نتیجه این است که هزاران افزونه بدون اینکه همدیگر را بشناسند کنار هم کار می‌کنند و شما هم بدون ویرایش هیچ فایل هسته یا افزونه‌ای تقریباً هر رفتاری را تغییر می‌دهید. هر چیزی که با آپدیت از بین نرود باید از طریق هوک انجام شود.

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

// اکشن: در لحظه‌ی چاپ فوتر کاری انجام بده
add_action( 'wp_footer', 'wpkala_footer_note' );

function wpkala_footer_note() {
	echo '<!-- ساخته‌شده با وردپرس کالا -->';
}

// فیلتر: مقدار را بگیر، تغییر بده و برگردان
add_filter( 'excerpt_length', 'wpkala_excerpt_length' );

function wpkala_excerpt_length( $length ) {
	return 30; // تعداد کلمات چکیده‌ی خودکار
}

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

آناتومی add_action و add_filter

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

// هوک wp_insert_post سه مقدار می‌دهد: شناسه، شیء نوشته و آیا به‌روزرسانی است
add_action( 'wp_insert_post', 'wpkala_after_insert', 10, 3 );

function wpkala_after_insert( $post_id, $post, $update ) {
	if ( $update || 'post' !== $post->post_type ) {
		return;
	}
	// فقط برای نوشته‌ی تازه ساخته‌شده
	update_post_meta( $post_id, '_wpkala_source', 'editor' );
}

closure ها کد را کوتاه می‌کنند و برای تغییرات ساده عالی‌اند، اما چون نام ندارند بعداً نمی‌توانید با remove_filter حذفشان کنید. برای قواعدی که ممکن است روزی بخواهید از جای دیگر خاموش کنید، تابع نام‌دار بنویسید:

// همان فیلتر با closure: کوتاه‌تر، اما بعداً قابل remove نیست
add_filter( 'excerpt_length', fn( $length ) => 30 );

کد هوک را کجا بگذاریم

functions.php با تغییر قالب از بین می‌رود. افزونه‌ی mu همیشه فعال و مستقل از قالب است و برای قواعد دائمی سایت بهترین جاست.

بیشتر آموزش‌ها می‌گویند «این کد را در functions.php بگذارید». مشکل این است که functions.php متعلق به قالب است؛ با عوض کردن قالب یا آپدیت آن، همه‌ی تغییرات شما می‌پرد. برای قواعدی که به قالب ربطی ندارند (امنیت، ایمیل، کرون، ووکامرس) جای درست یک افزونه‌ی must-use است: یک فایل PHP در پوشه‌ی wp-content/mu-plugins که بدون نصب و فعال‌سازی همیشه اجرا می‌شود و از پیشخوان قابل غیرفعال شدن نیست.

<?php
/**
 * Plugin Name: قواعد سایت وردپرس کالا
 * Description: هوک‌های اختصاصی سایت. فایل: wp-content/mu-plugins/wpkala-hooks.php
 */

defined( 'ABSPATH' ) || exit;

// همه‌ی مثال‌های این مقاله را می‌توانید زیر این خط بگذارید.

اگر پوشه‌ی mu-plugins وجود ندارد، بسازیدش. همه‌ی مثال‌های این مقاله را می‌توانید در همین فایل بگذارید. وقتی تعداد قواعد زیاد شد یا به صفحه‌ی تنظیمات نیاز داشتید، آن‌ها را به یک افزونه‌ی معمولی منتقل کنید؛ ساختار افزونه‌ی استاندارد را در مقاله‌ی ساخت بلاک سفارشی وردپرس کالا دیده‌اید.

ترتیب اجرای هوک‌ها

هر هوک در لحظه‌ی مشخصی اجرا می‌شود. کدی که روی هوک گذشته ثبت شود هرگز اجرا نمی‌شود.

رایج‌ترین دلیل «کدم کار نمی‌کند» همین ترتیب است. تابعی که مستقیم در فایل افزونه نوشته شود هنگام بارگذاری همان فایل اجرا می‌شود؛ یعنی قبل از init و قبل از اینکه کاربر فعلی، کوئری یا خیلی از توابع آماده باشند. راهنمای انتخاب هوک:

۲۰ مثال واقعی

همه‌ی مثال‌ها روی وردپرس ۶.۵ تا ۷.۱ تست شده‌اند و با PHP ۷.۴ به بالا کار می‌کنند. هر کدام را جداگانه در فایل mu-plugin بگذارید و بعد از هر تغییر یک بار سایت را باز کنید تا اگر خطایی هست همان لحظه ببینید.

محتوا و نمایش

// ۱) طول چکیده‌ی خودکار
add_filter( 'excerpt_length', fn() => 25, 999 );

// ۲) متن «[…]» انتهای چکیده
add_filter( 'excerpt_more', function () {
	return ' … <a class="more-link" href="' . esc_url( get_permalink() ) . '">ادامه‌ی مطلب</a>';
} );

// ۳) جعبه‌ی ثابت در پایان هر نوشته‌ی تکی
add_filter( 'the_content', 'wpkala_after_content', 20 );

function wpkala_after_content( $content ) {
	if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
		return $content;
	}
	$box = '<div class="wpkala-cta"><p>این مقاله مفید بود؟ در خبرنامه‌ی وردپرس کالا عضو شوید.</p></div>';
	return $content . $box;
}

سه شرط ابتدای مثال سوم را حذف نکنید: بدون in_the_loop() و is_main_query() جعبه‌ی شما داخل ویجت‌ها، بلاک‌های «نوشته‌های مرتبط» و حتی خلاصه‌ی فید هم ظاهر می‌شود.

// ۴) ثبت نوع نوشته‌ی «نمونه‌کار» (روی init، نه زودتر)
add_action( 'init', 'wpkala_register_portfolio' );

function wpkala_register_portfolio() {
	register_post_type( 'portfolio', array(
		'label'        => 'نمونه‌کارها',
		'public'       => true,
		'has_archive'  => true,
		'show_in_rest' => true, // برای ویرایشگر بلاکی و REST
		'menu_icon'    => 'dashicons-portfolio',
		'supports'     => array( 'title', 'editor', 'thumbnail', 'excerpt' ),
		'rewrite'      => array( 'slug' => 'portfolio' ),
	) );
}

// ۵) کلاس اختصاصی روی body برای استایل‌دهی شرطی
add_filter( 'body_class', function ( $classes ) {
	if ( is_user_logged_in() ) {
		$classes[] = 'is-logged-in';
	}
	if ( is_singular( 'product' ) ) {
		$classes[] = 'is-product';
	}
	return $classes;
} );

کوئری و فایل‌های ایستا

// ۶) تغییر تعداد نوشته‌ها فقط در آرشیو دسته، بدون دست زدن به تنظیمات
add_action( 'pre_get_posts', function ( $query ) {
	if ( is_admin() || ! $query->is_main_query() ) {
		return;
	}
	if ( $query->is_category() ) {
		$query->set( 'posts_per_page', 12 );
	}
	if ( $query->is_search() ) {
		$query->set( 'post_type', array( 'post', 'portfolio' ) );
	}
} );

// ۷) ثبت استایل و اسکریپت فقط در صفحه‌هایی که لازم است
add_action( 'wp_enqueue_scripts', function () {
	wp_enqueue_style( 'wpkala-site', get_stylesheet_directory_uri() . '/assets/site.css', array(), '1.2.0' );

	if ( is_singular( 'portfolio' ) ) {
		wp_enqueue_script( 'wpkala-gallery', get_stylesheet_directory_uri() . '/assets/gallery.js', array(), '1.2.0', array( 'strategy' => 'defer' ) );
	}
} );

پارامتر آخر wp_enqueue_script از وردپرس ۶.۳ آرایه می‌پذیرد و با 'strategy' => 'defer' اسکریپت را بدون مسدود کردن رندر بارگذاری می‌کند.

پاک‌سازی و امنیت

// ۸) حذف نسخه‌ی وردپرس و لینک‌های اضافه از head
remove_action( 'wp_head', 'wp_generator' );
remove_action( 'wp_head', 'wlwmanifest_link' );
remove_action( 'wp_head', 'rsd_link' );
remove_action( 'wp_head', 'wp_shortlink_wp_head' );

// ۹) حذف اسکریپت و استایل ایموجی
add_action( 'init', function () {
	remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
	remove_action( 'wp_print_styles', 'print_emoji_styles' );
	remove_action( 'admin_print_scripts', 'print_emoji_detection_script' );
	remove_action( 'admin_print_styles', 'print_emoji_styles' );
} );

// ۱۰) غیرفعال کردن XML-RPC (هدف رایج حمله‌های brute force)
add_filter( 'xmlrpc_enabled', '__return_false' );

حذف ایموجی روی هوک init انجام شده چون وردپرس خودش این اکشن‌ها را هنگام بارگذاری ثبت می‌کند و remove قبل از ثبت بی‌اثر است. دقت کنید اولویت ۷ در print_emoji_detection_script همان اولویتی است که وردپرس استفاده کرده؛ بدون آن حذف نمی‌شود.

ورود و کاربران

// ۱۱) پیام خطای ورود بدون لو دادن اینکه نام کاربری درست بوده
add_filter( 'login_errors', fn() => 'نام کاربری یا رمز عبور اشتباه است.' );

// ۱۲) هدایت بعد از ورود بر اساس نقش
add_filter( 'login_redirect', function ( $redirect_to, $requested, $user ) {
	if ( $user instanceof WP_User && in_array( 'subscriber', $user->roles, true ) ) {
		return home_url( '/my-account/' );
	}
	return $redirect_to;
}, 10, 3 );

ایمیل و رسانه

// ۱۳) فرستنده‌ی ایمیل‌های وردپرس (به جای wordpress@domain)
add_filter( 'wp_mail_from', fn() => 'info@wpkala.com' );
add_filter( 'wp_mail_from_name', fn() => 'وردپرس کالا' );

// ۱۴) اجازه‌ی آپلود SVG فقط به مدیران
add_filter( 'upload_mimes', function ( $mimes ) {
	if ( current_user_can( 'manage_options' ) ) {
		$mimes['svg'] = 'image/svg+xml';
	}
	return $mimes;
} );

آپلود SVG به صورت پیش‌فرض بسته است چون فایل SVG می‌تواند جاوااسکریپت داشته باشد. مثال ۱۴ فقط به مدیران اجازه می‌دهد؛ اگر نویسنده‌های زیادی دارید از افزونه‌ای استفاده کنید که SVG را پاک‌سازی می‌کند.

پیشخوان

// ۱۵) ستون «بازدید» در فهرست نوشته‌های پیشخوان
add_filter( 'manage_post_posts_columns', function ( $columns ) {
	$columns['wpkala_views'] = 'بازدید';
	return $columns;
} );

add_action( 'manage_post_posts_custom_column', function ( $column, $post_id ) {
	if ( 'wpkala_views' === $column ) {
		echo (int) get_post_meta( $post_id, 'views', true );
	}
}, 10, 2 );

// ۱۶) حذف ویجت‌های شلوغ پیشخوان
add_action( 'wp_dashboard_setup', function () {
	remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );   // اخبار وردپرس
	remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' ); // پیش‌نویس سریع
} );

رویدادها و دیدگاه

// ۱۷) وقتی نوشته‌ای برای اولین بار منتشر شد، کاری انجام بده (مثلاً اطلاع به تلگرام)
add_action( 'transition_post_status', function ( $new, $old, $post ) {
	if ( 'publish' !== $new || 'publish' === $old || 'post' !== $post->post_type ) {
		return;
	}
	wp_remote_post( 'https://example.ir/hooks/new-post', array(
		'timeout' => 5,
		'body'    => array( 'title' => $post->post_title, 'url' => get_permalink( $post ) ),
	) );
}, 10, 3 );

// ۱۸) حذف فیلد «وب‌سایت» از فرم دیدگاه (کمتر شدن اسپم)
add_filter( 'comment_form_default_fields', function ( $fields ) {
	unset( $fields['url'] );
	return $fields;
} );

هوک transition_post_status برای هر تغییر وضعیت اجرا می‌شود؛ شرط اول مطمئن می‌شود فقط اولین انتشار (نه ویرایش‌های بعدی) پیام بفرستد. درخواست خارجی را با timeout کوتاه بزنید تا اگر سرویس مقصد کند بود، انتشار نوشته معطل نماند.

ووکامرس و کرون

// ۱۹) متن دکمه‌ی خرید ووکامرس
add_filter( 'woocommerce_product_single_add_to_cart_text', fn() => 'همین حالا بخرید' );
add_filter( 'woocommerce_product_add_to_cart_text', function ( $text, $product ) {
	return $product->is_type( 'variable' ) ? 'انتخاب نسخه' : 'افزودن به سبد';
}, 10, 2 );

// ۲۰) کرون سفارشی هر ۱۵ دقیقه
add_filter( 'cron_schedules', function ( $schedules ) {
	$schedules['every_15_minutes'] = array( 'interval' => 15 * MINUTE_IN_SECONDS, 'display' => 'هر ۱۵ دقیقه' );
	return $schedules;
} );

add_action( 'init', function () {
	if ( ! wp_next_scheduled( 'wpkala_sync_prices' ) ) {
		wp_schedule_event( time(), 'every_15_minutes', 'wpkala_sync_prices' );
	}
} );

add_action( 'wpkala_sync_prices', function () {
	// همگام‌سازی قیمت‌ها با سرویس خارجی
} );

کرون وردپرس به بازدید کاربر وابسته است. برای اینکه رویداد هر ۱۵ دقیقه واقعاً اجرا شود، همان‌طور که در مقاله‌ی WP-CLI وردپرس کالا توضیح دادیم، کران‌جاب سیستمی را به wp cron event run --due-now وصل کنید.

اولویت و حذف هوک افزونه‌های دیگر

توابع به ترتیب اولویت اجرا می‌شوند و هر فیلتر خروجی قبلی را می‌گیرد. حذف تابع دیگران به نام تابع و اولویت دقیق نیاز دارد.

وقتی چند تابع به یک هوک وصل‌اند، وردپرس آن‌ها را از اولویت کم به زیاد اجرا می‌کند و در فیلترها خروجی هر کدام ورودی بعدی است. اگر می‌خواهید جعبه‌ی شما بعد از دکمه‌های اشتراک‌گذاری افزونه‌ای بیاید که با اولویت ۹۹ ثبت شده، اولویت ۱۰۰ بدهید. برای حذف تابع یک افزونه‌ی دیگر سه چیز باید دقیقاً یکی باشد: نام هوک، نام تابع و اولویت. و حذف باید بعد از ثبت انجام شود، پس آن را روی هوکی بنویسید که دیرتر از ثبت افزونه اجرا می‌شود:

// حذف تابعی که افزونه‌ی دیگری ثبت کرده: بعد از ثبت آن، پس روی هوک دیرتر
add_action( 'init', function () {
	remove_filter( 'the_content', 'share_plugin_buttons', 99 ); // همان نام تابع، همان اولویت
}, 20 );

// وقتی افزونه با کلاس ثبت کرده و شیء در دسترس نیست
add_action( 'init', function () {
	global $wp_filter;
	if ( empty( $wp_filter['the_content'] ) ) {
		return;
	}
	foreach ( $wp_filter['the_content']->callbacks as $priority => $callbacks ) {
		foreach ( $callbacks as $id => $cb ) {
			if ( is_array( $cb['function'] ) && $cb['function'][0] instanceof Some_Plugin_Class ) {
				remove_filter( 'the_content', $cb['function'], $priority );
			}
		}
	}
}, 20 );

برای پیدا کردن نام تابع و اولویت، کد افزونه را جست‌وجو کنید یا با این ابزار کوچک همه‌ی توابع وصل‌شده به یک هوک را ببینید:

// همه‌ی توابع وصل‌شده به یک هوک را ببینید
add_action( 'wp_footer', function () {
	if ( current_user_can( 'manage_options' ) && isset( $_GET['hooks'] ) ) {
		global $wp_filter;
		echo '<pre dir="ltr">';
		print_r( array_keys( $wp_filter['the_content']->callbacks ) ); // اولویت‌ها
		echo '</pre>';
	}
}, 999 );

ساخت هوک برای افزونه‌ی خودتان

اگر افزونه یا قالب می‌سازید، همان کاری را بکنید که وردپرس می‌کند: در نقاط مهم do_action و apply_filters بگذارید تا دیگران بدون ویرایش کد شما رفتارش را تغییر دهند. نام هوک‌ها را با پیشوند افزونه شروع کنید تا با هوک‌های دیگران تداخل نکند:

// در افزونه‌ی خودتان: به دیگران اجازه‌ی تغییر بدهید
function wpkala_render_price_box( $product_id ) {
	$price = get_post_meta( $product_id, '_price', true );

	// فیلتر: دیگران می‌توانند قیمت نمایشی را تغییر دهند
	$price = apply_filters( 'wpkala_display_price', $price, $product_id );

	echo '<div class="price-box">' . esc_html( number_format_i18n( $price ) ) . ' تومان</div>';

	// اکشن: دیگران می‌توانند زیر جعبه چیزی اضافه کنند
	do_action( 'wpkala_after_price_box', $product_id );
}

// در قالب یا افزونه‌ی دیگر:
add_filter( 'wpkala_display_price', fn( $price, $id ) => $price * 1.1, 10, 2 );
add_action( 'wpkala_after_price_box', fn( $id ) => print '<small>ارسال رایگان</small>' );

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

اشتباهات رایج و راه‌حل