معرفی تابع is_search() در وردپرس

تابع is_search() یکی از conditional tagهای وردپرس است که برای تشخیص صفحهٔ نتایج جستجو استفاده می‌شود. وقتی وردپرس یک درخواست را به عنوان «جستجو» شناسایی کند، این تابع مقدار true بازمی‌گرداند؛ در غیر این صورت false خواهد بود. این تابع برای کنترل نمایش قالب‌ها، تغییر پرس‌وجو و ایجاد رفتارهای مخصوص صفحهٔ جستجو بسیار مفید است.

خلاصهٔ کاربرد و مقدار بازگشتی

قواعد استفاده و نکات کلیدی

• این تابع باید پس از parse_query فراخوانی شود؛ معمولاً در قالب‌ها (مثل search.php) یا بعد از main query مناسب است.
• درون هوک‌هایی مثل pre_get_posts به جای is_search() از متد شیٔ query یعنی $query->is_search() استفاده کنید.
• در بخش مدیریت (admin) و برای درخواست‌های REST معمولاً is_search() به شکل متفاوتی عمل می‌کند؛ برای جلوگیری از تاثیر ناخواسته از is_admin() و بررسی is_main_query() بهره ببرید.
• نام فیلد جستجو باید s باشد؛ وردپرس بر پایه پارامتر query var به دنبال مقدار جستجو می‌گردد.

مثال‌های عملی

1) نمایش عنوان متفاوت در صفحهٔ نتایج جستجو (search.php)

if ( is_search() ) {
    echo '<h1>نتایج جستجوی: ' . esc_html( get_search_query() ) . '</h1>';
} else {
    echo '<h1>صفحهٔ آرشیو</h1>';
}

این قطعه در قالب search.php یا header.php قرار می‌گیرد تا در صورت صفحهٔ نتایج جستجو، عنوان مناسب همراه با عبارت جستجو را نشان دهد. تابع get_search_query() عبارت جستجو را برمی‌گرداند و esc_html() برای امنیت خروجی استفاده شده است.

2) اصلاح پرس‌وجوی جستجو با pre_get_posts

function my_modify_search( $query ) {
    // فقط فرانت‌اند و پرس‌وجوی اصلی
    if ( ! is_admin() && $query->is_main_query() && $query->is_search() ) {
        // فقط پست نوع 'post' را نمایش بده و هر صفحه 10 مورد باشد
        $query->set( 'post_type', array( 'post' ) );
        $query->set( 'posts_per_page', 10 );
        // براساس تاریخ مرتب کن
        $query->set( 'orderby', 'date' );
        $query->set( 'order', 'DESC' );
    }
}
add_action( 'pre_get_posts', 'my_modify_search' );

توضیح: این کد در فایل functions.php قرار می‌گیرد. شرط‌ها تضمین می‌کنند که تغییرات فقط در پرس‌وجوی اصلی و در بخش فرانت‌اند اعمال شوند. استفاده از $query->is_search() داخل pre_get_posts ضروری است چون is_search() سراسری ممکن است مقدار درست ندهد قبل از parse_query.

نکته بهینه‌سازی و اصلاح

function my_modify_search_fixed( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }

    if ( $query->is_search() ) {
        $query->set( 'post_type', array( 'post' ) );
        $query->set( 'posts_per_page', 10 );
    }
}
add_action( 'pre_get_posts', 'my_modify_search_fixed' );

در نسخهٔ اصلاح شده، با خروج زودهنگام (early return) خوانایی و کارایی بهتری حاصل شده و از پردازش غیرضروری جلوگیری می‌شود.

موارد رایج و مشکلات متداول

• فراخوانی is_search() خیلی زود: اگر قبل از parse_query فراخوانی شود ممکن است همیشه false بازگردد. بنابراین بهتر است در قالب‌ها یا هوک‌هایی که query آماده است از آن استفاده کنید.
• تداخل با پلاگین‌های جستجو: پلاگین‌هایی مثل Relevanssi یا SearchWP ممکن است رفتار صفحهٔ جستجو را تغییر دهند؛ در برخی موارد باید چک کنید که آن پلاگین‌ها چطور query vars را تنظیم می‌کنند.
• درخواست REST API: endpointهای REST معمولاً پارامترهای متفاوتی دارند و is_search() در آن‌ها کاربرد ندارد؛ برای REST از پارامترهای سرچ مربوطه استفاده کنید.

نمونه کاربردهای پیشرفته

ردیابی و آنالیز صفحات جستجو

می‌توانید وقتی is_search() true است، آرگومان‌های بوت‌استرپ آنالیتیکس یا دیتا-لایر را اضافه کنید تا عبارت‌های جستجو و نتایج را در گوگل آنالیتیکس دنبال کنید. توجه داشته باشید که برای قانون GDPR باید کاربر را آگاه کنید.

رویکرد اختصاصی برای هر نوع نوشته

function search_for_cpt( $query ) {
    if ( ! is_admin() && $query->is_main_query() && $query->is_search() ) {
        $query->set( 'post_type', array( 'post', 'product' ) );
    }
}
add_action( 'pre_get_posts', 'search_for_cpt' );

این کد نتایج جستجو را برای انواع نوشتهٔ ‘post’ و ‘product’ (مثال: ووکامرس) محدود می‌کند. اگر می‌خواهید فقط محصولات نمایش داده شوند، کافی است آرایه را تغییر دهید.

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

• همیشه خروجی عبارت جستجو را با توابع امن‌کننده مثل esc_html() یا esc_attr() چاپ کنید.
• در تغییر پرس‌وجو از شرط‌های مناسب (is_admin، is_main_query) استفاده کنید تا تغییرات ناخواسته در بخش مدیریت یا کوئری‌های داخلی رخ ندهد.
• اگر فرم جستجوی سفارشی می‌سازید، نام فیلد مقدار باید s باشد تا وردپرس آن را به‌عنوان query var شناسایی کند.

جمع‌بندی

تابع is_search() ابزار ساده و در عین حال قدرتمندی برای تشخیص صفحهٔ نتایج جستجو در وردپرس است. با ترکیب آن در قالب‌ها و هوک‌هایی مثل pre_get_posts می‌توانید تجربهٔ جستجوی سفارشی، بهینه‌سازی نتایج و نمایش‌های مخصوص را پیاده‌سازی کنید. به یاد داشته باشید که در هوک‌ها از متد شیء query استفاده کنید و همیشه امنیت و عملکرد را مدنظر قرار دهید.

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

ارسال