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

توابع وردپرس چیست؟

تابع وردپرس، بخشی از کد PHP است که یک وظیفهٔ مشخص انجام می‌دهد و از پیش در هسته، قالب یا افزونه‌های فعال تعریف شده است. سه لایهٔ اصلی وجود دارد: یک — توابع هسته. در wp-includes/ و wp-admin/includes/. این توابع، پایهٔ کار با وردپرس هستند: get_option، get_post، wp_insert_post، sanitize_text_field. دو — توابع قالب (Template Tags). توابعی که در فایل‌های قالب برای نمایش داده به‌کار می‌روند: the_title، the_content، the_permalink، get_header. این دسته، پرکاربردترین توابع در کار روزمره است. سه — توابع افزونه و قالب سفارشی. توابعی که خودتان یا افزونه‌های دیگر تعریف می‌کنید: my_plugin_get_data، mytheme_customize_logo. مقایسهٔ این سه لایه در همین مقاله و افزونهٔ وردپرس چیست آمده است.

توابع وردپرس، پل بین کد شما و هستهٔ سیستم‌اند؛ بدون تسلط بر آن‌ها، هر کاری شبیه بازآفرینی چرخ است.

ساختار و روش فراخوانی

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

// فراخوانی بدون پارامتر
$site_name = get_bloginfo( 'name' );

// فراخوانی با پارامتر
$post = get_post( 42 );

// فراخوانی با چند پارامتر
$args = array( 'post_type' => 'post', 'posts_per_page' => 10 );
$query = new WP_Query( $args );

// فراخوانی با مقدار پیش‌فرض
$value = get_option( 'my_key', 'default' );

سه نکته: یک — بررسی مقدار بازگشتی. بعضی توابع، مقدار برمی‌گردانند؛ بعضی، هم مقدار و هم خطا (WP_Error). همیشه is_wp_error را پس از توابعی مثل wp_remote_get یا get_terms چک کنید. دو — فراخوانی در زمان درست. بعضی توابع (مثل is_user_logged_in) فقط بعد از هوک init کار می‌کنند. سه — ترتیب لود. توابعی که در یک فایل تعریف شده‌اند، فقط پس از لود شدن آن فایل قابل فراخوانی هستند. راهنمای هوک‌ها در هوک‌های وردپرس و استفادهٔ درست از هوک‌ها.

دسته‌بندی توابع بر اساس کاربرد

توابع وردپرس در هشت دستهٔ اصلی قرار می‌گیرند:

دستهنمونه توابعکاربرد
نمایش دادهthe_title، the_content، the_permalinkنمایش محتوا در قالب
دریافت دادهget_the_title، get_post، get_userdataخواندن داده برای پردازش
شرطیis_singular، is_home، has_post_thumbnailبررسی وضعیت صفحه
ذخیره‌سازیwp_insert_post، update_option، update_post_metaنوشتن داده در دیتابیس
امنیتsanitize_text_field، esc_html، wp_nonce_fieldپاک‌سازی و escape
لینک و URLhome_url، get_permalink، admin_urlساخت URL استاندارد
نوع‌نوشته و تاکسونومیregister_post_type، get_terms، get_the_termsمدیریت ساختار محتوا
کاربر و دسترسیcurrent_user_can، wp_get_current_user، is_user_logged_inمدیریت کاربر و مجوزها

این دسته‌بندی، در تشخیص سریع تابع مناسب کمک می‌کند. مرجع کامل هر دسته در توابع داده‌های نوشته، توابع کاربران، توابع متادیتا، و توابع لینک و URL آمده است.

پیشوندها و منطق نام‌گذاری

نام توابع وردپرس، الگوی مشخصی دارند که با فهم آن، حدس زدن رفتار تابع آسان می‌شود: یک — get_: مقدار برمی‌گرداند، چیزی چاپ نمی‌کند. مثال: get_the_title، get_option، get_post_meta. دو — the_: مقدار را چاپ می‌کند. مثال: the_title، the_content، the_permalink. سه — is_: مقدار بولی برمی‌گرداند. مثال: is_home، is_singular، is_user_logged_in. چهار — has_: بررسی وجود یک ویژگی. مثال: has_post_thumbnail، has_category. پنج — add_: افزودن. مثال: add_action، add_filter، add_shortcode. شش — update_: به‌روزرسانی. مثال: update_option، update_post_meta. هفت — delete_: حذف. مثال: delete_option، delete_post_meta. هشت — register_: ثبت. مثال: register_post_type، register_taxonomy، register_widget. نه — wp_: توابع عمومی هسته. مثال: wp_insert_post، wp_remote_get. ده — _e()، __(): توابع ترجمه. مثال: __() مقدار برمی‌گرداند، _e() چاپ می‌کند. این الگوها در استانداردهای کدنویسی وردپرس رسمی شده‌اند و در خواندن کد هسته، کمک بزرگی می‌کنند.

Template Tags: توابع نمایش

Template Tags، توابع ویژه‌ای هستند که در فایل‌های قالب برای نمایش محتوا به‌کار می‌روند. سه دستهٔ کاربردی:

یک — نمایش نوشتهٔ جاری در حلقه:

while ( have_posts() ) : the_post();
    the_title( '<h2>', '</h2>' );
    the_excerpt();
    the_post_thumbnail( 'medium' );
    the_content();
    the_permalink();
endwhile;

دو — نمایش اطلاعات سایت:

bloginfo( 'name' );               // نام سایت
get_bloginfo( 'description' );     // توضیح سایت
home_url( '/contact' );            // URL صفحهٔ اصلی + مسیر
admin_url( 'post-new.php' );       // URL پیشخوان
wp_logout_url();                   // URL خروج

سه — نمایش بخش‌های قالب:

get_header();
get_sidebar( 'primary' );
get_footer();
get_template_part( 'template-parts/content', get_post_type() );

نکتهٔ مهم: تفاوت the_* و get_the_*. توابع the_* مقدار را چاپ می‌کنند؛ توابع get_the_* مقدار را برمی‌گردانند. برای استفاده در sprintf یا concatenation، از get_* استفاده کنید. مرجع کامل در توابع داده‌های نوشته و ساختار فایل‌های قالب استاندارد. یک نکتهٔ امنیتی: بعضی از این توابع، خروجی را escape می‌کنند (the_title با esc_html) و بعضی نمی‌کنند (the_content با محتوای HTML). همیشه بدانید کدام تابع، خروجی را escape می‌کند؛ در صورت شک، از esc_html یا wp_kses_post استفاده کنید. راهنما در پاک‌سازی داده‌ها.

توابع شرطی

توابع شرطی، برای بررسی وضعیت صفحه به‌کار می‌روند. سه گروه اصلی: یک — نوع صفحه:

is_home()           // صفحهٔ اصلی وبلاگ
is_front_page()     // صفحهٔ اصلی سایت
is_singular()       // نوشته، برگه یا CPT مشخص
is_single()         // نوشتهٔ تکی
is_page()           // برگه
is_category()       // آرشیو دسته
is_tag()            // آرشیو برچسب
is_search()         // نتایج جستجو
is_404()            // صفحهٔ خطا
is_archive()        // هر آرشیو

دو — ویژگی محتوا:

has_post_thumbnail()          // آیا تصویر شاخص دارد؟
has_excerpt()                 // آیا خلاصه دارد؟
has_category( 'news' )        // آیا در دستهٔ خبر است؟
has_tag()                     // آیا برچسب دارد؟
has_block( 'core/paragraph' ) // آیا بلوک خاصی دارد؟

سه — وضعیت کاربر و محیط:

is_user_logged_in()        // آیا کاربر لاگین است؟
current_user_can( 'edit_posts' )  // آیا دسترسی ویرایش دارد؟
is_admin()                 // آیا در پیشخوان هستیم؟
is_rtl()                   // آیا زبان راست‌به‌چپ است؟
wp_is_mobile()             // آیا کاربر موبایل است؟

نکته: توابع شرطی در functions.php پیش از هوک wp قابل اعتماد نیستند. اگر لازم است در زمان لود، شرطی را بررسی کنید، از هوک wp یا template_redirect استفاده کنید. راهنمای هوک‌ها در هوک‌های وردپرس و تفاوت اکشن و فیلتر.

توابع داده‌محور

توابع داده‌محور، داده را از دیتابیس می‌خوانند یا در آن می‌نویسند. سه گروه اصلی:

یک — خواندن داده:

get_post( $post_id );                            // نوشته کامل
get_posts( array( 'post_type' => 'post' ) );      // لیست نوشته‌ها
get_post_meta( $post_id, '_key', true );          // متادیتای نوشته
get_option( 'my_key', 'default' );                // گزینه
get_userdata( $user_id );                         // کاربر
get_user_meta( $user_id, '_key', true );          // متادیتای کاربر
get_terms( array( 'taxonomy' => 'category' ) );   // ترم‌ها

دو — نوشتن داده:

wp_insert_post( $args );                          // افزودن نوشته
wp_update_post( $args );                          // به‌روزرسانی نوشته
update_post_meta( $post_id, '_key', $value );     // ذخیرهٔ متادیتا
update_option( 'my_key', $value );                 // ذخیرهٔ گزینه
update_user_meta( $user_id, '_key', $value );     // ذخیرهٔ متادیتای کاربر

سه — حذف داده:

wp_delete_post( $post_id, true );              // حذف کامل
delete_post_meta( $post_id, '_key' );           // حذف متادیتا
delete_option( 'my_key' );                      // حذف گزینه
delete_user_meta( $user_id, '_key' );           // حذف متادیتای کاربر

نکته: در نوشتن داده، همیشه پاک‌سازی و اعتبارسنجی انجام دهید. راهنمای کامل در کار با متاباکس‌ها، کار با User Meta، کار با Options API، و اعتبارسنجی داده‌ها.

تفاوت توابع و هوک‌ها

یک تفکیک رایج که درک درست آن، کل معماری وردپرس را روشن می‌کند: تابع، یک وظیفهٔ مشخص انجام می‌دهد. مثال: get_post_meta متادیتا را می‌خواند. هوک، نقطهٔ اتصال است. یک تابع را در زمان اجرای مشخص، به هسته وصل می‌کند. مثال: add_action( 'init', 'my_function' ) — تابع my_function را به هوک init وصل می‌کند. تفاوت کلیدی: هوک‌ها خودشان تابع نیستند؛ آن‌ها تابعی هستند که تابع دیگری را در زمان مشخص ثبت می‌کنند. تفصیل کامل در هوک‌های وردپرس و راهنمای حرفه‌ای هوک‌ها. یک قاعدهٔ عملی: هر عملکرد اختصاصی که با هوک ثبت می‌شود، خودش یک تابع سفارشی است. بنابراین تفکیک «تابع» و «هوک» در سطح مفهومی روشن است، ولی در عمل به‌هم‌پیوسته کار می‌کنند.

توابع سفارشی: ساخت و استفاده

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

if ( ! function_exists( 'my_plugin_get_customer_name' ) ) {
    function my_plugin_get_customer_name( $user_id ) {
        $user = get_userdata( $user_id );
        if ( ! $user ) {
            return '';
        }
        $custom_name = get_user_meta( $user_id, '_customer_name', true );
        return $custom_name ? $custom_name : $user->display_name;
    }
}

سه نکته: یک — function_exists: امکان جایگزینی توسط افزونه‌های دیگر یا چایلد تم. دو — پارامترها: با نوع و مقدار پیش‌فرض صریح. سه — مقدار بازگشتی: پیوسته و قابل پیش‌بینی. الگوهای بیشتر در کدنویسی اختصاصی افزونه و ساختار فایل‌های افزونهٔ استاندارد. در پروژهٔ چند‌ساله، تفاوت بین تابع با پیشوند و تابع عمومی، در روز برخورد با افزونهٔ دیگری که همان نام را انتخاب کرده، ظاهر می‌شود.

جایگزینی توابع والد

در چایلد تم، می‌توانید توابع والد را جایگزین کنید — به شرطی که والد آن‌ها را با function_exists محافظت کرده باشد:

// در چایلد تم
if ( ! function_exists( 'parent_theme_function' ) ) {
    function parent_theme_function() {
        // پیاده‌سازی جدید شما
    }
}

نکته: اگر والد تابعش را محافظت نکرده باشد، جایگزینی مستقیم ممکن نیست. راه‌حل‌ها: استفاده از هوک‌های والد، یا remove_action و remove_filter قبل از افزودن نسخهٔ سفارشی. راهنمای کامل در چایلد تم، توسعه با چایلد تم، و حذف اکشن هوک. یک نکتهٔ ظریف: جایگزینی توابع والد، در بعضی پروژه‌ها به اشتباه انجام می‌شود. اگر والد تابعی را از طریق هوک ثبت کرده، بهتر است از همان هوک استفاده کنید تا از سلسله‌مراتب خارج نشوید. راهنما در راهنمای حرفه‌ای هوک‌ها.

امنیت در فراخوانی توابع

هر فراخوانی تابع، یک نقطهٔ بالقوهٔ آسیب‌پذیری است. پنج قاعدهٔ الزامی: یک — پاک‌سازی ورودی. قبل از استفاده از دادهٔ کاربر، از sanitize_text_field، absint، esc_url_raw استفاده کنید. دو — escape خروجی. در نمایش، از esc_html، esc_attr، esc_url استفاده کنید. سه — بررسی دسترسی. قبل از هر عملیات حساس، current_user_can. چهار — nonce. در فرم‌ها و درخواست‌های AJAX، wp_verify_nonce. پنج — آماده‌سازی کوئری. در کوئری خام، $wpdb->prepare. نمونه:

function my_plugin_save_data( $post_id ) {
    // بررسی nonce
    if ( ! isset( $_POST['my_nonce'] ) || ! wp_verify_nonce( $_POST['my_nonce'], 'my_action' ) ) {
        return;
    }
    // بررسی دسترسی
    if ( ! current_user_can( 'edit_post', $post_id ) ) {
        return;
    }
    // پاک‌سازی ورودی
    $title = sanitize_text_field( wp_unslash( $_POST['my_title'] ) );
    // ذخیره
    update_post_meta( $post_id, '_my_title', $title );
}

راهنمای کامل در PHP امن در وردپرس، پاک‌سازی داده‌ها، اعتبارسنجی داده‌ها، و نانس وردپرس.

کارایی در فراخوانی

توابع وردپرس، همه با یک هزینه همراه‌اند. چهار تکنیک سبک‌سازی: یک — انتخاب تابع کم‌هزینه. get_the_ID سریع‌تر از get_post است، اگر فقط ID لازم است. دو — کش نتیجهٔ توابع سنگین. اگر تابعی محاسبهٔ سنگینی دارد یا به دیتابیس می‌زند، با Transients کش کنید. سه — کاهش فراخوانی در حلقه. هر فراخوانی تابع درون حلقه، تکرار می‌شود. با جمع‌آوری داده قبل از حلقه، فراخوانی‌ها را کاهش دهید. چهار — استفاده از توابع تخصصی. به‌جای فراخوانی چند تابع برای یک کار، از تابعی که همه‌چیز را یک‌جا می‌دهد استفاده کنید. مثال:

// نامناسب - سه فراخوانی
$post = get_post( $post_id );
$author = get_userdata( $post->post_author );
$terms = get_the_terms( $post_id, 'category' );

// بهتر - با یک کوئری ترکیبی
$query = new WP_Query( array(
    'p' => $post_id,
    'post_type' => 'any',
) );
if ( $query->have_posts() ) :
    $query->the_post();
    $author = get_userdata( get_the_author_meta( 'ID' ) );
    $terms = get_the_terms( get_the_ID(), 'category' );
endif;
wp_reset_postdata();

راهنمای کامل در بهینه‌سازی کد وردپرس، بهینه‌سازی کوئری‌ها، و ترنزینت‌ها در وردپرس. در پروژه‌ای که صفحهٔ اصلی با ده فراخوانی تکراری درون حلقه اجرا می‌شد، تجمیع آن‌ها در سه فراخوانی، تعداد کوئری‌ها را از ۴۵ به ۶ کاهش داد.

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

توابع وردپرس، پایهٔ کار توسعه‌دهنده هستند. تسلط بر آن‌ها، سه لایه دارد: شناخت (چه توابعی وجود دارد)، درک (هر تابع چه کاری می‌کند و چه نمی‌کند)، و انتخاب (کدام تابع برای این مسئلهٔ مشخص، بهترین گزینه است). در این مقاله، هشت دسته‌بندی، پنج نوع پیشوند، و سه گروه اصلی توابع (Template Tags، شرطی، داده‌محور) را مرور کردیم. اگر امروز یک کار در این مسیر انجام می‌دهید: فهرست توابع پرکاربرد در افزونهٔ فعلی خود را بنویسید و ببینید کدام‌یک را می‌توانید با تابع هستهٔ وردپرس جایگزین کنید؛ هر جایگزینی، یک خط کد کمتر و یک لایهٔ استاندارد بیشتر است. اگر تجربه‌ای از یک تابع وردپرس دارید که مدتی برای پیدا کردنش وقت گذاشته‌اید — یا تابعی که جایگزین کد سفارشی کرده‌اید — در دیدگاه‌ها بنویسید؛ همان گزارش‌های واقعی، این راهنما را برای نفر بعدی دقیق‌تر می‌کند. 🧩