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

تابع get_search_query() یکی از توابع ساده و در عین حال پرکاربرد وردپرس است که متن عبارت جستجو شده را از کوئری جاری دریافت می‌کند. این تابع معمولاً در فرم‌های جستجو، عنوان نتایج و هر جایی که نیاز به نمایش عبارت جستجو برای کاربر داریم استفاده می‌شود. در این مقاله به صورت کامل نحوهٔ کار، پارامترها، مثال‌های عملی، نکات امنیتی و حالات پیشرفته را بررسی می‌کنیم.

کاربرد کلی

این تابع مقدار متغیر کوئری «s» را واکشی می‌کند و آن را برای نمایش آماده می‌کند. به عبارت دیگر اگر کاربر عبارت «کتاب برنامه‌نویسی» را جستجو کند، get_search_query() همین عبارت را برمی‌گرداند تا بتوانیم در فیلد ورودی یا عنوان نتایج نشان دهیم.

امضای تابع و پارامترها

تفاوت با get_query_var(‘s’)

• get_query_var(‘s’) مقدار خام متغیر کوئری را برمی‌گرداند. معمولاً شامل اسلَش‌ها یا کاراکترهایی می‌شود که ممکن است نیاز به sanitization داشته باشند.
• get_search_query() یک لایهٔ ساده فراردهی/sanitize دارد (به‌صورت پیش‌فرض escapes) و برای نمایش در فرم‌ها مناسب‌تر است.

نمونهٔ پایه در searchform.php

<form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
  <label>
    <span class="screen-reader-text">Search for:</span>
    <input type="search" class="search-field" placeholder="جستجو…" value="<?php echo get_search_query(); ?>" name="s" />
  </label>
  <button type="submit">جستجو</button>
</form>

توضیح: این مثال فرم جستجوی ساده‌ای را نشان می‌دهد که در آن مقدار پیش‌فرض فیلد جستجو با استفاده از get_search_query() پر می‌شود. چون get_search_query() به‌صورت پیش‌فرض خروجی را escaped می‌کند، استفادهٔ مستقیم آن در value امن است. با این حال برای اطمینان بیشتر از esc_attr می‌توان استفاده کرد.

نمایش عبارت جستجو در عنوان صفحه نتایج

<h1 class="search-title">
  <?php printf( esc_html__( 'نتایج جستجو برای: %s', 'textdomain' ), get_search_query() ); ?>
</h1>

توضیح: این کد عنوان صفحهٔ نتایج را به‌شکل محلی‌سازی‌شده نشان می‌دهد. از آنجا که get_search_query() مقدار را فراردهی می‌کند، ترکیب آن با esc_html__ و printf مطمئن و مناسب برای خروجی است.

دریافت مقدار خام (بدون escaping)

$raw_query = get_search_query( false );
// سپس می‌توانیم sanitize یا پردازش خاص خود را انجام دهیم:
$clean = sanitize_text_field( $raw_query );

توضیح: اگر به مقدار خام برای پردازش‌های سفارشی نیاز دارید (مثلاً برای تحلیل کلمات، جستجوی مرتبط یا ارسال به سرویس خارجی)، می‌توانید get_search_query(false) را فراخوانی کنید و سپس با توابع امن‌سازی مثل sanitize_text_field آن را تمیز کنید. هرگز مقدار خام را مستقیماً در HTML چاپ نکنید.

نکات امنیتی و بهترین روش‌ها

• همیشه پیش از چاپ در HTML از esc_attr یا esc_html استفاده کنید مگر آنکه مطمئن باشید تابع مورد استفاده خودش escape انجام داده باشد.
• اگر get_search_query(false) را گرفتید، آن را با sanitize_text_field() یا توابع مناسب دیگر پاک کنید.
• برای فرم‌ها از esc_url( home_url(‘/’) ) در action استفاده کنید تا آدرس امن باشد.

مثال پیشرفته: حفظ پارامترهای پیشرفته در فرم

<?php
// فرض: می‌خواهیم query پارامترهای دیگری نیز در فرم نگه داشته شوند، مثل دسته‌بندی یا فیلتر تاریخ
$category = isset( $_GET['category'] ) ? sanitize_text_field( wp_unslash( $_GET['category'] ) ) : '';
?>

<form method="get" action="<?php echo esc_url( home_url( '/' ) ); ?>">
  <input type="search" name="s" value="<?php echo esc_attr( get_search_query() ); ?>" />
  <input type="hidden" name="category" value="<?php echo esc_attr( $category ); ?>" />
  <button type="submit">جستجو</button>
</form>

توضیح: این سناریو نشان می‌دهد چگونه می‌توان پارامترهای اضافی (مثل category) را در فرم نگه داشت. از wp_unslash و sanitize_text_field برای دریافت امن دادهٔ GET استفاده شده و سپس با esc_attr هنگام چاپ فراردهی می‌شود.

فیلترها و توسعهٔ بیشتر

تابع get_search_query() مقدار را قبل از بازگرداندن معمولاً از طریق فیلترهایی قابل تغییر می‌کند (apply_filters). توسعه‌دهندگان می‌توانند با هوک مناسب مقدار را تغییر دهند — مثلاً برای پاک‌سازی اضافی یا افزودن منطق محلی‌سازی.

مثال تغییر مقدار با فیلتر

add_filter( 'get_search_query', 'my_custom_search_query', 10, 1 );
function my_custom_search_query( $query ) {
    // به عنوان نمونه کاراکترهای خاص را حذف می‌کنیم
    $query = preg_replace( '/[^p{L}p{N}s]/u', '', $query );
    return $query;
}

توضیح: این کد نشان می‌دهد چگونه با استفاده از هوک get_search_query می‌توان قبل از نمایش، رشتهٔ جستجو را دست‌کاری یا تمیز کرد. در این مثال کاراکترهای غیرحروف و اعداد حذف می‌شوند. دقت کنید که دست‌کاری‌های سنگین ممکن است تجربهٔ کاربر را تغییر دهد و باید با احتیاط انجام شود.

موارد حرفه‌ای و نکات اضافی

• برای سایت‌های چندزبانه، همیشه از توابع محلی‌سازی (مثل __() یا _e()) در کنار get_search_query استفاده کنید تا متن‌های رابط کاربری ترجمه‌پذیر بمانند.
• در صفحات کش‌شده (cached) توجه داشته باشید که فرم جستجو باید مقدار کاربر را به‌درستی نشان دهد؛ استفاده از جاوااسکریپت برای پر کردن فیلد پس از لود ممکن است در برخی حالت‌ها منطقی‌تر باشد.
• برای جستجوهای AJAX بهتر است از sanitize_text_field بر روی ورودی سمت سرور استفاده کنید و برای نمایش در نتیجه‌بخش HTML، از توابع escape مناسب بهره ببرید.

خلاصه

تابع get_search_query() ابزاری ساده اما ضروری برای نمایش عبارت جستجو در وردپرس است. با درک تفاوت بین مقدار خام و مقدار escaped، استفادهٔ درست در فرم‌ها و قالب‌ها، و رعایت نکات امنیتی می‌توانید تجربهٔ کاربری بهتری فراهم کنید. در پروژه‌های پیشرفته‌تر از فیلترها و sanitize/escape مناسب استفاده کنید تا هم عملکرد و هم امنیت سایت حفظ شود.

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

ارسال