۱۰ فیلتر پرکاربرد وردپرس که باید بشناسید

اولین فیلتری که واقعاً در پروژه‌ای جدی به دادم رسید، the_content بود؛ سه ساعت وقت صرف کرده بودم تا در ده‌ها فایل قالب، یک دکمه اشتراک‌گذاری اضافه کنم — بعد با یک فیلتر سه‌خطی، همه آن کارها حذف شد. تجربه‌ام در پروژه‌های واقعی نشان داده که حدود ۹۰ درصد نیازهای روزمره توسعه در وردپرس، با ده فیلتر پرکاربرد قابل حل است؛ فیلترهایی که اگر بشناسید، دیگر برای هر تغییر کوچک سراغ فایل‌های قالب نمی‌روید. فیلترهای پرکاربرد وردپرس بخشی از آن لایه‌ای هستند که تفاوت بین یک توسعه‌دهنده سطح متوسط و یک توسعه‌دهنده حرفه‌ای را مشخص می‌کند: یکی برای هر تغییر دنبال جای مناسب در کد می‌گردد، دیگری از قبل می‌داند کدام هوک وظیفه‌اش را انجام می‌دهد. اگر با مفهوم کلی فیلتر آشنا نیستید، ابتدا فیلترها در وردپرس: تغییر رفتار بدون دستکاری هسته را بخوانید تا لایه‌های زیرین این فهرست را درک کنید.

چرا شناخت فیلترهای پرکاربرد این‌قدر مهم است؟

در پروژه‌های وردپرسی، اکثر تغییرات کوچک — از اضافه کردن یک متن به انتهای همه نوشته‌ها تا تغییر رنگ دکمه ورود — با فیلترها قابل پیاده‌سازی است. اما خیلی از توسعه‌دهندگان به‌جای استفاده از فیلترها، سراغ ویرایش فایل قالب یا هسته می‌روند؛ نتیجتاً، پس از هر آپدیت، تغییراتشان پاک می‌شود یا سایت به حالت ناپایدار می‌افتد. شناخت فیلترهای پرکاربرد، این مشکل را از ریشه حل می‌کند. تجربه من در پروژه‌های سازمانی، یک الگوی مشخص را نشان می‌دهد: تیم‌هایی که فیلترها را خوب می‌شناسند، کد تمیزتری می‌نویسند، در زمان کمتری تغییرات را پیاده می‌کنند، و در آپدیت‌های هسته، دردسر کمتری دارند.

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

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

۱. the_content: کلید دسترسی به محتوای نوشته

فیلتر the_content، پرکاربردترین فیلتر وردپرس است. این فیلتر، محتوای نوشته را پیش از نمایش نهایی عبور می‌دهد و به شما اجازه می‌دهد آن را تغییر دهید. کاربردهای واقعی این فیلتر بسیار متنوع است. از اضافه کردن یک پیام به انتهای همه نوشته‌ها، تا درج خودکار تبلیغ، جعبه اشتراک‌گذاری، جدول مطالب، لینک‌های مرتبط، و حتی اصلاح ساختار HTML خروجی. در پروژه‌های خودم، از این فیلتر برای اضافه کردن «بخش مقالات مرتبط» بر اساس دسته‌بندی هر نوشته استفاده می‌کنم؛ به‌جای ویرایش فایل single.php در قالب، یک فیلتر سه‌خطی که هم با آپدیت قالب پاک نمی‌شود، هم قابل کنترل‌تر است.

ساختار استاندارد استفاده از این فیلتر به این شکل است:

add_filter( 'the_content', 'wpkar_add_footer_to_posts' );
function wpkar_add_footer_to_posts( $content ) {
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content;
    }
    $content .= '<div class="author-box">' . esc_html( get_the_author() ) . '</div>';
    return $content;
}

سه نکته مهم در استفاده از این فیلتر. اول، شرط‌های سه‌گانه که در کد بالا می‌بینید (is_singular، in_the_loop، is_main_query) ضروری هستند چون فیلتر the_content در مکان‌های غیرمنتظره هم اجرا می‌شود — مثلاً در نمایش خلاصه نوشته‌ها، در نتایج جستجو، و حتی در برخی بخش‌های پیشخوان. اگر این شرط‌ها را نگذارید، ممکن است متن اضافه‌شده در جاهایی ظاهر شود که نمی‌خواستید. دوم، پاک‌سازی خروجی با توابع مثل esc_html و wp_kses_post ضروری است تا از حمله XSS جلوگیری شود. سوم، اولویت‌بندی: اگر افزونه دیگری هم به همین فیلتر متصل است، ترتیب اجرا بر اساس اولویت مشخص می‌شود. برای درک عمیق‌تر نحوه مدیریت اولویت، Priority در هوک‌های وردپرس چیست راهنمای جامعی است.

۲. the_title: تغییر عنوان بدون تغییر دیتابیس

فیلتر the_title، عنوان نوشته را پیش از نمایش تغییر می‌دهد. برخلاف آنچه تصور می‌شود، تغییر در دیتابیس نیاز نیست؛ فقط در مسیر رسیدن به کاربر، عنوان تغییر می‌کند. کاربردهای واقعی این فیلتر: اضافه کردن پیشوند یا پسوند به عنوان‌ها بر اساس شرایط (مثلاً «فوری: …» برای نوشته‌های دسته خبری)، حذف کلمات غیرضروری، یا اضافه کردن امتیاز به عنوان محصولات. یک مثال کاربردی در پروژه فروشگاهی که داشتم: افزودن کلمه «جدید» به عنوان محصولاتی که در هفت روز گذشته منتشر شده‌اند.

add_filter( 'the_title', 'wpkar_prefix_new_products', 10, 2 );
function wpkar_prefix_new_products( $title, $post_id ) {
    if ( get_post_type( $post_id ) !== 'product' ) {
        return $title;
    }
    $days_since = ( time() - get_post_time( 'U', true, $post_id ) ) / DAY_IN_SECONDS;
    if ( $days_since < 7 ) {
        return '🔵 جدید | ' . $title;
    }
    return $title;
}

نکته مهم در این فیلتر: the_title در همه جا اجرا می‌شود — در آرشیو، در صفحه تکی، در پیشخوان، و حتی در API. اگر می‌خواهید تغییرتان فقط در فرانت‌اند اعمال شود، حتماً از is_admin() برای جلوگیری از اعمال در پیشخوان استفاده کنید. نکته دوم: خروجی این فیلتر، در تگ <title> صفحه هم اعمال می‌شود؛ پس اگر تغییر شما طولانی باشد، ممکن است طول تگ عنوان در گوگل کوتاه شود. برای درک بهتر مدیریت طول عنوان در سئو، نقش عنوان و توضیحات در CTR را بخوانید.

۳. the_excerpt و excerpt_length: کنترل خلاصه نوشته

فیلترهای the_excerpt و excerpt_length، دو فیلتر مکمل برای کنترل خلاصه نوشته هستند. فیلتر excerpt_length تعداد کلمات خلاصه را تغییر می‌دهد و فیلتر the_excerpt محتوای خلاصه را. این دو فیلتر، در پروژه‌های محتوایی بسیار کاربردی هستند چون اکثر قالب‌ها از خلاصه نوشته در آرشیو استفاده می‌کنند. اگر می‌خواهید خلاصه‌های سایت شما کوتاه‌تر یا بلندتر باشند، این دو فیلتر نقطه شروع شما هستند.

add_filter( 'excerpt_length', 'wpkar_custom_excerpt_length', 999 );
function wpkar_custom_excerpt_length( $length ) {
    if ( is_admin() ) {
        return $length;
    }
    return 25;
}

add_filter( 'excerpt_more', 'wpkar_custom_excerpt_more' );
function wpkar_custom_excerpt_more( $more ) {
    if ( is_admin() ) {
        return $more;
    }
    return ' … ' . '<a href="' . esc_url( get_permalink() ) . '">ادامه</a>';
}

نکته مهم: در فیلتر excerpt_length، استفاده از اولویت ۹۹۹ ضروری است چون برخی افزونه‌ها ممکن است به همین فیلتر متصل باشند و شما می‌خواهید بعد از آن‌ها اجرا شوید. نکته دوم: فیلتر excerpt_more که در مثال بالا استفاده شده، فیلتر مکمل است که متن «ادامه مطلب» را کنترل می‌کند. اگر در قالب شما خلاصه نوشته با «[…]» نمایش داده می‌شود، با این فیلتر می‌توانید آن را به یک متن دلخواه و لینک‌دار تغییر دهید. برای مطالعه بیشتر در مورد توابع مرتبط با نوشته، توابع وردپرس برای دریافت اطلاعات نوشته راهنمای دقیقی است.

۴. wp_mail: بازنویسی ایمیل پیش از ارسال

فیلتر wp_mail، یکی از پرکاربردترین فیلترها در پروژه‌های سازمانی است. این فیلتر، آرایه‌ای از پارامترهای ایمیل را پیش از ارسال عبور می‌دهد و به شما اجازه می‌دهد آن را تغییر دهید. کاربردهای رایج: بازنویسی آدرس گیرنده در محیط‌های استجینگ (تا ایمیل‌ها به مشتریان واقعی نروند)، تغییر فرستنده، افزودن سربرگ‌های SMTP، و تنظیم نوع محتوا. در پروژه‌ای که محیط استجینگ و تولید جدا داشت، این فیلتر نجات‌دهنده بود: کدی نوشتیم که در استجینگ، همه ایمیل‌ها را به یک آدرس تست ارسال می‌کرد.

add_filter( 'wp_mail', 'wpkar_redirect_emails_in_staging', 10, 3 );
function wpkar_redirect_emails_in_staging( $args, $subject, $message ) {
    if ( wp_get_environment_type() !== 'staging' ) {
        return $args;
    }
    $args['to'] = 'test@example.com';
    $args['subject'] = '[STAGING] ' . $subject;
    return $args;
}

سه نکته مهم. اول، wp_get_environment_type() در وردپرس ۵.۵ به بعد وجود دارد و مقادیر «local»، «development»، «staging» یا «production» برمی‌گرداند. این تابع، ابزار استانداردی برای تشخیص محیط است. دوم، همیشه return $args را فراموش نکنید — چون فیلتر است و مقدار بازگشتی دارد. سوم، در محیط تولید، این فیلتر را برای بازنویسی کامل غیرفعال کنید چون ممکن است خطرناک باشد. اگر با پیکربندی ایمیل در وردپرس آشنا نیستید، پیکربندی ایمیل‌های وردپرس راهنمای کاملی است. و اگر می‌خواهید مشکل عدم ارسال ایمیل را عیب‌یابی کنید، خطای ارسال ایمیل در وردپرس و راه حل آن نقطه شروع مناسبی است.

۵. login_redirect: هدایت هوشمند کاربران پس از ورود

فیلتر login_redirect، مسیر پس از ورود کاربر را تغییر می‌دهد. در پروژه‌های سازمانی که کاربران با نقش‌های مختلف — مدیر، ویرایشگر، مشتری، فروشنده — وارد می‌شوند، هدایت همه آن‌ها به یک مسیر واحد تجربه خوبی نمی‌سازد. با این فیلتر، می‌توانید هر نقش را به داشبورد مخصوص خودش هدایت کنید. مثلاً مشتریان به صفحه «سفارش‌های من»، فروشندگان به صفحه «محصولات من»، و مدیران به پیشخوان. این تکنیک، در پروژه‌های فروشگاهی چندفروشندگی (Multi-Vendor) بسیار کاربردی است.

add_filter( 'login_redirect', 'wpkar_custom_login_redirect', 10, 3 );
function wpkar_custom_login_redirect( $redirect_to, $requested, $user ) {
    if ( ! is_wp_error( $user ) && isset( $user->roles ) ) {
        if ( in_array( 'customer', $user->roles, true ) ) {
            return home_url( '/my-account/orders/' );
        }
        if ( in_array( 'shop_manager', $user->roles, true ) ) {
            return home_url( '/shop-dashboard/' );
        }
    }
    return $redirect_to;
}

نکته مهم: همیشه بررسی کنید که $user یک آبجکت معتبر باشد و نقش کاربر را با in_array با پارامتر سوم true (مقایسه strict) بررسی کنید. اگر با سیستم نقش‌ها و دسترسی‌ها در وردپرس آشنا نیستید، تنظیمات کاربران و نقش‌ها در وردپرس راهنمای دقیقی است. برای تقویت امنیت ورود، چگونه ورود ادمین وردپرس را امن کنیم؟ را هم ببینید.

۶. wp_nav_menu_items: منوی داینامیک بدون دستکاری قالب

فیلتر wp_nav_menu_items، به شما اجازه می‌دهد آیتم‌های منو را به‌صورت داینامیک تغییر دهید. کاربردهای واقعی: اضافه کردن یک دکمه «تماس با ما» به انتهای منو، اضافه کردن نام کاربر جاری به منو، یا اضافه کردن لینک ورود/خروج بر اساس وضعیت کاربر. این فیلتر، در پروژه‌های سازمانی که منو باید بر اساس شرایط داینامیک تغییر کند، بسیار کاربردی است.

add_filter( 'wp_nav_menu_items', 'wpkar_add_login_link_to_menu', 10, 2 );
function wpkar_add_login_link_to_menu( $items, $args ) {
    if ( $args->theme_location !== 'primary' ) {
        return $items;
    }
    if ( is_user_logged_in() ) {
        $url = wp_logout_url( home_url() );
        $items .= '<li class="menu-item menu-item-logout"><a href="' . esc_url( $url ) . '">خروج</a></li>';
    } else {
        $items .= '<li class="menu-item menu-item-login"><a href="' . esc_url( wp_login_url() ) . '">ورود</a></li>';
    }
    return $items;
}

سه نکته مهم. اول، حتماً بررسی کنید که منو مربوطه، همان منویی است که می‌خواهید (با $args->theme_location). چون این فیلتر در همه منوهای سایت اجرا می‌شود. دوم، خروجی HTML باید با ساختار منوی وردپرس سازگار باشد؛ هر آیتم باید <li> با کلاس‌های مناسب داشته باشد. سوم، همیشه از esc_url و esc_html برای پاک‌سازی خروجی استفاده کنید. برای مطالعه بیشتر در مورد توابع مربوط به منو، توابع وردپرس برای مدیریت منوها راهنمای دقیقی است.

۷. upload_mimes: کنترل انواع فایل آپلودی

فیلتر upload_mimes، لیست انواع فایل مجاز برای آپلود را کنترل می‌کند. به‌صورت پیش‌فرض، وردپرس فرمت‌های محدودی را می‌پذیرد و فرمت‌هایی مثل SVG یا WebP را در نسخه‌های قدیمی نمی‌پذیرفت. با این فیلتر، می‌توانید فرمت‌های اضافی را فعال یا فرمت‌های خطرناک را غیرفعال کنید. کاربرد رایج: فعال کردن آپلود SVG برای لوگو و آیکون‌ها. اما توجه: آپلود SVG یک ریسک امنیتی جدی است چون SVG می‌تواند شامل JavaScript اجرایی باشد.

add_filter( 'upload_mimes', 'wpkar_add_svg_webp_support' );
function wpkar_add_svg_webp_support( $mimes ) {
    $mimes['svg']  = 'image/svg+xml';
    $mimes['webp'] = 'image/webp';
    return $mimes;
}

نکته مهم امنیتی: فیلتر upload_mimes فقط نوع فایل را بررسی می‌کند و محتوای آن را پاک‌سازی نمی‌کند. اگر SVG را فعال می‌کنید، حتماً یک افزونه یا کد اضافی برای پاک‌سازی SVG از کدهای خطرناک اضافه کنید. برای درک عمیق‌تر امنیت در وردپرس، راهنمای امنیت وردپرس برای مبتدیان راهنمای جامعی است. برای بهینه‌سازی تصاویر و آپلود کارآمد، بهترین فرمت تصویر برای وب کدام است؟ را هم بخوانید.

۸. body_class: کلاس‌های شرطی برای CSS هوشمند

فیلتر body_class، کلاس‌های CSS تگ <body> را تغییر می‌دهد. وردپرس به‌صورت پیش‌فرض کلاس‌هایی مثل home، single، page-id-123 را اضافه می‌کند. با این فیلتر، می‌توانید کلاس‌های شرطی اضافه کنید تا CSS شما هوشمندتر شود. کاربردهای واقعی: اضافه کردن کلاس برای کاربران وارد‌شده (تا بتوانید استایل متفاوتی به آن‌ها بدهید)، کلاس برای نوع دستگاه (موبایل یا دسکتاپ)، یا کلاس برای روز هفته. مثلاً در پروژه‌ای، کلاس is-member را به بدنه اضافه کردیم تا برای کاربران عضو، رنگ پس‌زمینه متفاوتی اعمال شود.

add_filter( 'body_class', 'wpkar_add_custom_body_classes' );
function wpkar_add_custom_body_classes( $classes ) {
    if ( is_user_logged_in() ) {
        $classes[] = 'is-logged-in';
        $user = wp_get_current_user();
        foreach ( $user->roles as $role ) {
            $classes[] = 'role-' . sanitize_html_class( $role );
        }
    }
    if ( wp_is_mobile() ) {
        $classes[] = 'device-mobile';
    }
    return $classes;
}

نکته مهم: از sanitize_html_class برای پاک‌سازی نام کلاس‌ها استفاده کنید تا از تزریق CSS یا XSS جلوگیری شود. نکته دوم: کلاس‌های خیلی زیاد، HTML را سنگین می‌کند و در صورت انباشت، بر سرعت اثر می‌گذارد. به تعداد محدود کلاس‌های ضروری اکتفا کنید. برای مطالعه بیشتر در مورد CSS و طراحی، CSS مدرن: از Flexbox تا Grid راهنمای مفیدی است.

۹. wp_get_attachment_image_attributes: کنترل ویژگی‌های تصویر

فیلتر wp_get_attachment_image_attributes، به شما اجازه می‌دهد ویژگی‌های HTML تصویر (مثل alt، loading، sizes، و class) را پیش از رندر تغییر دهید. کاربردهای واقعی: اضافه کردن fetchpriority="high" به تصاویر LCP، تنظیم loading بر اساس مکان تصویر در صفحه، یا افزودن کلاس‌های CSS سفارشی به تصاویر. در پروژه‌ای که عملکرد Core Web Vitals بحرانی بود، از این فیلتر برای بهبود LCP استفاده کردیم.

add_filter( 'wp_get_attachment_image_attributes', 'wpkar_optimize_image_attrs', 10, 3 );
function wpkar_optimize_image_attrs( $attr, $attachment, $size ) {
    if ( $size === 'full' && is_singular() ) {
        $attr['fetchpriority'] = 'high';
        $attr['loading']       = 'eager';
    }
    return $attr;
}

نکته مهم: فیلتر wp_get_attachment_image_attributes در همه تصاویر سایت اجرا می‌شود، پس حتماً با شرط‌های دقیق محدودش کنید. برای درک عمیق‌تر Core Web Vitals، Core Web Vitals چیست و چرا گوگل بر آن تاکید دارد؟ را بخوانید. برای مطالعه بیشتر درباره توابع مرتبط با تصویر، توابع وردپرس برای مدیریت رسانه‌ها راهنمای دقیقی است.

۱۰. woocommerce_product_get_price: قیمت داینامیک در ووکامرس

فیلتر woocommerce_product_get_price، قیمت محصول را در مسیر رسیدن به کاربر تغییر می‌دهد. این فیلتر یکی از پرکاربردترین فیلترهای ووکامرس است و در پروژه‌های فروشگاهی که قیمت بر اساس شرایط داینامیک تغییر می‌کند، نقشی حیاتی دارد. کاربردهای واقعی: قیمت متفاوت برای کاربران همکار (Wholesale)، قیمت با تخفیف بر اساس تعداد سفارش، یا قیمت متفاوت بر اساس منطقه جغرافیایی. در پروژه‌ای، این فیلتر را برای تخفیف ۱۵ درصدی به مشتریان B2B استفاده کردیم.

add_filter( 'woocommerce_product_get_price', 'wpkar_wholesale_price', 10, 2 );
function wpkar_wholesale_price( $price, $product ) {
    if ( ! is_user_logged_in() ) {
        return $price;
    }
    if ( ! wc_current_user_has_role( 'wholesale_customer' ) ) {
        return $price;
    }
    if ( is_admin() && ! wp_doing_ajax() ) {
        return $price;
    }
    return $price * 0.85;
}

سه نکته حیاتی در استفاده از این فیلتر. اول، همیشه شرط is_admin() را بگذارید تا قیمت در پیشخوان تغییر نکند — وگرنه مدیر سایت قیمت اشتباه را ذخیره می‌کند. دوم، از wp_doing_ajax() برای موارد AJAX استفاده کنید چون در برخی حالت‌های AJAX (مثل به‌روزرسانی سبد خرید)، نمی‌خواهید قیمت دوباره محاسبه شود. سوم، در فیلترهای ووکامرس، همیشه آبجکت $product را بررسی کنید چون ممکن است در بعضی موارد null باشد. اگر می‌خواهید درک عمیق‌تری از سفارشی‌سازی ووکامرس داشته باشید، سفارشی‌سازی صفحه محصول در ووکامرس و ووکامرس را در عمل بشناسید راهنماهای مفیدی هستند.

فیلتر woocommerce_product_get_price، ساده‌ترین راه تغییر قیمت در ووکامرس است — اما همین فیلتر، یکی از پرخطرترین نقاط ممکن برای باگ اگر شرط‌های is_admin و wp_doing_ajax را فراموش کنید.

فیلترهای مکمل که در پروژه‌ها زیاد به‌کارم می‌آیند

علاوه بر ده فیلتر بالا، پنج فیلتر مکمل وجود دارد که در پروژه‌های واقعی به‌طور مکرر به‌کارم می‌آیند. اولین، wp_redirect که پیش از ریدایرکت کاربر اجرا می‌شود و به شما اجازه می‌دهد شرط‌های اضافی اضافه کنید. دوم، comments_open که وضعیت باز یا بسته بودن دیدگاه‌ها را کنترل می‌کند. سوم، pre_get_posts که یکی از قدرتمندترین فیلترهای وردپرس است و به شما اجازه می‌دهد کوئری اصلی وردپرس را پیش از اجرا تغییر دهید — مثلاً حذف دسته‌بندی خاصی از آرشیو، یا تغییر ترتیب نمایش. اگر می‌خواهید درک عمیق‌تری از این فیلتر داشته باشید، بهینه‌سازی کوئری‌های وردپرس با کدنویسی راهنمای دقیقی است.

چهارمین فیلتر مکمل، user_contactmethods که فیلدهای پروفایل کاربر را تغییر می‌دهد. پنجمین، wp_setup_nav_menu_item که ویژگی‌های هر آیتم منو را پیش از رندر تغییر می‌دهد. اگر می‌خواهید فهرست کامل‌تری از فیلترهای پرکاربرد ببینید، مهم‌ترین Filter Hook های وردپرس راهنمای جامعی است. و اگر در حال توسعه افزونه هستید، هوک‌های وردپرس در توسعه افزونه چه کاربردی دارند را بخوانید تا الگوهای حرفه‌ای را یاد بگیرید.

جدول خلاصه: ده فیلتر و کاربرد یک‌خطی

پرسش‌های پرتکرار درباره فیلترهای پرکاربرد وردپرس

مهم‌ترین فیلتر وردپرس که هر توسعه‌دهنده باید بشناسد کدام است؟

فیلتر the_content پرکاربردترین فیلتر وردپرس است چون بیشترین تعداد کاربردهای روزمره را پوشش می‌دهد — از اضافه کردن محتوا به انتهای نوشته‌ها تا اصلاح ساختار HTML خروجی. اما فیلترهای دیگر مثل pre_get_posts و wp_mail در پروژه‌های خاص، نقش کلیدی دارند.

چطور از فیلتر the_content استفاده کنم؟

از تابع add_filter برای متصل کردن callback به فیلتر the_content استفاده کنید. همیشه سه شرط is_singular، in_the_loop و is_main_query را در ابتدای callback بررسی کنید تا تغییرات در جاهای غیرمنتظره اعمال نشود.

چرا در فیلتر the_content باید return داشته باشم؟

چون فیلترها به‌صورت زنجیره‌ای اجرا می‌شوند. خروجی هر callback، ورودی callback بعدی است. اگر return فراموش شود، مقدار null جایگزین محتوا می‌شود و صفحه سفید یا محتوای خالی نمایش داده می‌شود.

چطور می‌توانم قیمت محصول را در ووکامرس تغییر دهم؟

با فیلتر woocommerce_product_get_price. این فیلتر قیمت محصول را در مسیر رسیدن به کاربر تغییر می‌دهد. حتماً شرط‌های is_admin و wp_doing_ajax را اضافه کنید تا قیمت در پیشخوان و در AJAX تغییر نکند.

تفاوت the_title با the_content چیست؟

هر دو فیلتر هستند اما روی داده‌های متفاوتی اعمال می‌شوند. the_title عنوان نوشته را تغییر می‌دهد و the_content محتوای نوشته را. هر دو در سراسر وردپرس در نقاط کلیدی اجرا می‌شوند و باید با شرط‌های دقیق محدود شوند.

چطور می‌توانم در محیط استجینگ ایمیل‌ها را بازنویسی کنم؟

با فیلتر wp_mail و تشخیص محیط با wp_get_environment_type(). در callback، اگر محیط استجینگ بود، آدرس گیرنده را به یک آدرس تست تغییر دهید و در موضوع ایمیل یک پیشوند مثل [STAGING] اضافه کنید.

چرا فیلتر body_class برای سئو مهم است؟

فیلتر body_class به‌تنهایی برای سئو مهم نیست، اما کلاس‌های شرطی که به بدنه اضافه می‌کنید، امکان شخصی‌سازی CSS را فراهم می‌کنند. این شخصی‌سازی می‌تواند تجربه کاربری را بهبود بخشد که غیرمستقیم بر سئو اثر می‌گذارد.

آیا می‌توانم فیلترهای زیادی به یک صفحه اضافه کنم؟

فنی ممکن است، اما توصیه نمی‌شود. هر فیلتر در هر بار بارگذاری یک هزینه پردازشی دارد. اگر callback شما کوئری سنگین، فراخوانی API، یا محاسبات پیچیده دارد، این هزینه در هر بار بارگذاری صفحه پرداخت می‌شود. راه‌حل: از کش استفاده کنید و شرطی کردن اجرا را جدی بگیرید.

چطور فیلتر نامناسب را حذف کنم؟

با تابع remove_filter. باید همان نام فیلتر، همان callback، همان اولویت، و همان تعداد پارامترهایی که در add_filter استفاده کرده‌اید را مشخص کنید. توابع بی‌نام (anonymous functions) را نمی‌توان حذف کرد؛ همیشه از توابع نام‌دار استفاده کنید.

کدام فیلتر برای بهینه‌سازی Core Web Vitals مهم‌تر است؟

فیلتر wp_get_attachment_image_attributes به شما اجازه می‌دهد fetchpriority="high" و loading تصویر را بر اساس مکان تصویر در صفحه تنظیم کنید که مستقیماً بر LCP اثر می‌گذارد. فیلتر body_class هم می‌تواند برای شرایط خاص مفید باشد، اما اثر آن روی CWV غیرمستقیم است.

آیا فیلترها می‌توانند در گوتنبرگ هم استفاده شوند؟

بله، اکثر فیلترها در گوتنبرگ کار می‌کنند چون گوتنبرگ از همان مکانیزم هوک‌های هسته وردپرس استفاده می‌کند. برای فیلترهای مخصوص گوتنبرگ، از فیلترهای JavaScript مخصوص Block Editor استفاده می‌شود که در مستندات رسمی وردپرس توضیح داده شده است.

چطور بفهمم کدام فیلتر در صفحه‌ای که می‌خواهم، وجود دارد؟

ابزار اصلی، افزونه Query Monitor است که فهرست تمام فیلترهای اجراشده را با جزئیات کامل نشان می‌دهد. همچنین می‌توانید در کد منبع وردپرس یا افزونه مربوطه، تابع apply_filters را جستجو کنید. برای یادگیری عمیق‌تر این موضوع، دیباگ کردن Action و Filter در وردپرس راهنمای دقیقی است.

از فهرست فیلترها تا عادت معماری

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

سه نکته عملی که در پروژه‌های واقعی بیشترین اثر را داشته‌اند. اول، همیشه شرط‌ها را جدی بگیرید — is_admin، is_singular، in_the_loop و is_main_query شرط‌هایی هستند که به ظاهر کوچک‌اند اما از بروز بسیاری از باگ‌ها جلوگیری می‌کنند. دوم، خروجی را حتماً پاک‌سازی کنید — esc_html، esc_url و wp_kses_post سه ابزار ضروری در هر فیلتر هستند. سوم، عملکرد را جدی بگیرید — هر فیلتر اضافه، هزینه‌ای در هر بار بارگذاری پرداخت می‌کند؛ با کش کردن نتایج، شرطی کردن اجرا، و محدود نگه داشتن تعداد فیلترها، می‌توانید هم انعطاف‌پذیری و هم سرعت را حفظ کنید.

اگر در پروژه‌ای با یک فیلتر کاربردی روبرو شده‌اید که در این فهرست نبود — یا اگر در استفاده از یکی از این ده فیلتر به چالش خورده‌اید — تجربه‌تان را در دیدگاه‌ها بنویسید. برای من جالب است بدانم کدام فیلتر بیشترین نقش را در پروژه‌های شما ایفا کرده و کدام یک، بیشترین درس را به شما داده است. به‌خصوص اگر راه‌حل خلاقانه‌ای برای یک مسئله پیچیده با فیلترها پیدا کرده‌اید، بازخوردتان می‌تواند برای تیم‌های فنی دیگر یک میان‌بر ارزشمند باشد. 🎯