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

تابع get_query_var() یکی از ابزارهای کلیدی وردپرس برای دستیابی به متغیرهای پرس‌وجو (query vars) است. این تابع اجازه می‌دهد مقدار پارامترهایی که وردپرس در فرایند ساخت صفحه استخراج کرده است را در قالب‌ها، افزونه‌ها یا توابع سفارشی بخوانیم. در این مقاله به جزئیات فنی، نمونه‌های واقعی، بهترین روش‌ها و نکات امنیتی می‌پردازیم.

get_query_var چیست و چگونه کار می‌کند؟

get_query_var($var, $default = ”) مقدار یک متغیر پرس‌وجو را برمی‌گرداند. وردپرس قبل از رندر صفحات، پارامترهای URL و بازنویسی (rewrite) را به یک آرایه query_vars تبدیل می‌کند و get_query_var صرفاً مقدار آن متغیر را از شیء global $wp_query خوانده و بازمی‌گرداند.

• پارامترها: $var (نام متغیر)، $default (اختیاری، مقدار پیش‌فرض در صورت عدم وجود)
• محل مناسب استفاده: بعد از اینکه پرس‌وجو اجرا شده؛ مثلاً در قالب‌ها، hook های template_redirect یا در توابعی که بعد از parse_request اجرا می‌شوند.

مثال ساده: خواندن شماره صفحه (paged)

// در فایل قالب (مثلاً archive.php یا index.php)
$paged = get_query_var('paged', 1);

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

متغیرهای معمول query_vars

افزودن query var دلخواه

برای پذیرش متغیر دلخواه در URL ابتدا باید آن را ثبت کنید تا وردپرس اجازه خواندن آن را بدهد. دو مرحله لازم است:

• اضافه کردن متغیر به لیست query_vars با فیلتر query_vars
• ایجاد قوانین بازنویسی (rewrite rules) برای ساخت URL پاک (friendly URLs)

// افزودن query var دلخواه
add_filter('query_vars', function($vars){
    $vars[] = 'myvar';
    return $vars;
});

// اضافه کردن rewrite tag و rule
add_action('init', function(){
    add_rewrite_tag('%myvar%', '([^&]+)');
    add_rewrite_rule('^myroute/([^/]+)/?','index.php?myvar=$matches[1]','top');
});

در این کد، ابتدا myvar به آرایه query_vars اضافه می‌شود. سپس با add_rewrite_tag و add_rewrite_rule یک مسیر پاک مشابه /myroute/value/ تعریف می‌شود که مقدار value را در myvar قرار می‌دهد.

نکته مهم: پس از اضافه کردن قواعد جدید باید یکبار flush_rewrite_rules() انجام شود (مثلاً در فعال‌سازی افزونه یا دستی از بخش تنظیمات > پیوندهای یکتا)، تا قواعد جدید اعمال شوند.

خواندن متغیر دلخواه از طریق get_query_var

// در قالب یا هک بعد از parse_request
$myvalue = get_query_var('myvar', '');
if ($myvalue !== '') {
    // پردازش با $myvalue
}

این کد مقدار myvar را می‌خواند. همواره بهتر است مقدار ورودی را قبل از استفاده پاک‌سازی (sanitize) کنید.

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

• همیشه مقادیر خوانده‌شده را با توابع مناسب پاک‌سازی کنید: برای متن از sanitize_text_field() یا esc_attr() و برای اعداد از intval() یا absint() استفاده کنید.
• از get_query_var برای اجرای مستقیم دستورهای حساس پایگاه‌داده یا ساخت دستورات SQL بدون اعتبارسنجی استفاده نکنید.

$myvalue = get_query_var('myvar', '');
$myvalue = sanitize_text_field($myvalue);

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

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

• $wp_query->get(‘var’): معادل داخلی است؛ get_query_var در واقع همین اطلاعات را از global $wp_query می‌گیرد.
• $_GET: مقادیر مستقیم پارامترهای کوئری را می‌خواند اما شامل بازنویسی و تفسیر وردپرس نیست (برای URL های پاک کاربرد ندارد).
• WP_Query args: برای ساخت یک پرس‌وجوی جدید از مصادیق WP_Query استفاده می‌کنیم؛ get_query_var برای خواندن پرس‌وجوی جاری مناسب‌تر است.

مثال کاربردی: فیلتر کردن آرشیو محصول بر اساس پارامتر سفارشی

// در functions.php یا افزونه
add_filter('query_vars', function($vars){
    $vars[] = 'price_range';
    return $vars;
});

add_action('pre_get_posts', function($query){
    if (!is_admin() && $query->is_main_query() && is_post_type_archive('product')) {
        $range = get_query_var('price_range', '');
        if ($range) {
            // فرض کنید range به صورت min-max است
            list($min, $max) = array_map('intval', explode('-', $range));
            $meta_query = array(
                array(
                    'key' => 'price',
                    'value' => array($min, $max),
                    'compare' => 'BETWEEN',
                    'type' => 'NUMERIC'
                )
            );
            $query->set('meta_query', $meta_query);
        }
    }
});

در این سناریو با استفاده از get_query_var(‘price_range’) مقدار ارسال شده در URL خوانده می‌شود و سپس به کمک pre_get_posts پرس‌وجوی اصلی برای آرشیو محصولات فیلتر می‌شود. همیشه ورودی را به‌درستی تبدیل و اعتبارسنجی کنید تا از خطا یا حملات جلوگیری شود.

نکات حرفه‌ای و بهترین روش‌ها

• متغیرها را تنها زمانی ثبت کنید که واقعاً نیاز دارید؛ اضافه کردن بیش از حد query_vars می‌تواند پیچیدگی‌ ایجاد کند.
• قواعد بازنویسی را در اکشن init اضافه کنید و flush_rewrite_rules را تنها در هنگام فعال‌سازی/غیرفعال‌سازی افزونه اجرا کنید.
• از get_query_var در hook هایی که قبل از parse_request اجرا می‌شوند استفاده نکنید، زیرا مقدار هنوز تنظیم نشده است.
• برای تست، ابتدا از روش query string ساده (?myvar=foo) استفاده کنید و بعد سراغ rewrite-friendly URLs بروید.

جمع‌بندی

get_query_var() یک ابزار ساده اما قدرتمند برای دسترسی به متغیرهای پرس‌وجوی وردپرس است. با ترکیب آن با query_vars، add_rewrite_rule و pre_get_posts می‌توانید مسیرهای سفارشی، فیلترهای قدرتمند و تجربه کاربری بهتری ایجاد کنید. اما همیشه به امنیت و ترتیب اجرای توابع توجه کنید تا رفتار مورد انتظار حاصل شود.

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

ارسال