آموزش تابع set_query_var() در وردپرس و کاربرد آن

در وردپرس هنگام توسعه قالب یا پلاگین ممکن است نیاز داشته باشید داده‌ای را در سطح درخواست (request) بین بخش‌های مختلف قالب منتقل کنید. یکی از روش‌های رایج برای این کار استفاده از توابع set_query_var() و get_query_var() است. این مقاله به طور جامع عملکرد، موارد استفاده، مثال‌های عملی و بهترین شیوه‌ها را توضیح می‌دهد.

set_query_var() چیست و چگونه کار می‌کند؟

تابع set_query_var( $var, $value ) یک مقدار را در آبجکت سراسری WP_Query ثبت می‌کند. این مقدار فقط در طول همان درخواست HTTP ذخیره می‌شود و در درخواست‌های بعدی پایدار نمی‌ماند. برای خواندن مقدار ثبت‌شده می‌توان از get_query_var( $var ) استفاده کرد.

چرا و چه زمانی باید از آن استفاده کرد؟

• ارسال متغیر از فایل والد به یک Template Part (قبل از اینکه وردپرس امکان args در get_template_part را اضافه کند).
• اشتراک داده بین فانکشن‌هایی که در نقاط مختلف لود اجرای قالب فراخوانی می‌شوند (مثلاً بین functions.php و header.php).
• تست‌ها یا تنظیماتی که فقط برای پاسخ فعلی نیاز به نگهداری دارند و نباید در دیتابیس ذخیره شوند.

مثال ساده — ارسال داده به template part

/* در فایل قالب اصلی (مثلاً index.php) */set_query_var( 'special_message', 'سلام از قالب اصلی' );
get_template_part( 'template-parts/content' );

/* در فایل template-parts/content.php */$message = get_query_var( 'special_message' );
echo esc_html( $message );

در این مثال، ابتدا با set_query_var متغیری به نام special_message تنظیم شده و سپس template part بارگذاری می‌شود. داخل آن با get_query_var مقدار بازیابی و نمایش داده می‌شود. این روش برای ارسال داده‌های ساده بین فایل‌ها سریع و موثر است.

مثال پیشرفته — کنترل نمایش کارت محصول

// در قالب که لیست محصولات را تولید می‌کند
set_query_var( 'show_price', true );
get_template_part( 'template-parts/product/card' );

// در template-parts/product/card.php
$show_price = get_query_var( 'show_price' );
if ( $show_price ) {
    echo '<div class="price">' . esc_html( get_post_meta( get_the_ID(), '_price', true ) ) . '</div>';
}

با این روش می‌توانید یک کارت محصول را در جاهای مختلف قالب با رفتارهای گوناگون (نمایش یا عدم نمایش قیمت، دکمه‌ها و …) استفاده کنید بدون تکرار کامل کد.

تفاوت set_query_var با روش‌های دیگر

روش مدرن و توصیه‌شده

از وردپرس 5.5 به بعد می‌توانید هنگام فراخوانی get_template_part آرایه‌ای از آرگومان‌ها ارسال کنید: get_template_part( ‘slug’, null, $args ). این روش صریح‌تر و کمتر خطاپذیر است و در عین حال بسیاری از کاربردهای set_query_var را پوشش می‌دهد.

// توصیه شده (WP 5.5+)
$args = array( 'show_price' => true );
get_template_part( 'template-parts/product/card', null, $args );

// در template-parts/product/card.php
if ( ! empty( $args['show_price'] ) ) {
    // نمایش قیمت
}

این روش خوانایی بهتر و ایزوله‌سازی بهتری برای آرایه آرگومان‌ها فراهم می‌کند و تداخل نام احتمالی با query vars را کاهش می‌دهد.

نکات فنی و چالش‌ها

• set_query_var روی آبجکت سراسری WP_Query کار می‌کند؛ در بخش‌هایی مثل REST API یا درخواست‌های AJAX که از WP_Query متفاوت استفاده می‌شود ممکن است رفتار متفاوتی مشاهده شود.
• نام متغیرها را به گونه‌ای انتخاب کنید که احتمال تداخل با query vars موجود یا افزونه‌ها کم باشد (مثلاً prefix اختصاصی).
• اگر نیاز دارید متغیر از URL قابل خواندن باشد (مثلاً example.com/?my_var=1)، باید از فیلتر query_vars استفاده و rewrite rule مناسب ایجاد کنید؛ set_query_var برای این منظور کاربردی نیست.

مثال: اضافه کردن query var از URL

// ثبت نام متغیر مجاز
add_filter( 'query_vars', function( $vars ) {
    $vars[] = 'my_custom_var';
    return $vars;
});

// استفاده در template
$value = get_query_var( 'my_custom_var', '' );

در این سناریو اگر URL شامل ?my_custom_var=value باشد، get_query_var مقدار را برمی‌گرداند. توجه داشته باشید که برای خواندن پارامترهای URL نیازی به set_query_var نیست.

بهترین شیوه‌ها (Best Practices)

• برای ارسال داده بین قالب‌ها ابتدا بررسی کنید آیا get_template_part با args نیاز شما را برآورده می‌کند یا خیر.
• از prefix اختصاصی برای نام متغیرها استفاده کنید تا تداخل جلوگیری شود (مثلاً mytheme_show_price).
• از sanitize و esc هنگام خروجی‌دهی استفاده کنید تا آسیب‌پذیری XSS ایجاد نشود.
• در صورتی که داده باید در چند درخواست نگهداری شود، از transients یا metadata استفاده کنید؛ set_query_var مناسب نگهداری بین درخواست‌ها نیست.

جمع‌بندی و توصیه نهایی

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

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

ارسال