آن شب که یک فیلتر سفارشی، فروشگاه را قابل تنظیم کرد

اواخر سال ۱۳۹۸، یک فروشگاه اینترنتی لوازم خانگی را تحویل گرفتم که مدیر بازاریابی‌اش هر هفته یک درخواست تازه داشت: «این هفته قیمت‌ها را ۵ درصد کم کنیم»، «این هفته برای مشتری‌های VIP تخفیف ویژه بگذاریم»، «این هفته قیمت‌های بالای ۱۰ میلیون را گرد کنیم». من به‌جای نوشتن کد جداگانه برای هر سناریو، یک فیلتر سفارشی روی myshop_calculate_final_price ساختم. سپس هر بار که مدیر بازاریابی درخواست تازه‌ای داشت، به‌جای ویرایش کد افزونه، فقط چند خط callback روی همان فیلتر اضافه می‌کردیم. آن پروژه به من یاد داد که فیلتر سفارشی، کلید تبدیل افزونه‌ای با منطق ثابت به یک پلتفرم با منطق قابل تنظیم است. این مقاله، تجربه‌ام در ساخت فیلتر سفارشی است که در پروژه‌های واقعی به‌کار می‌برم. اگر با مفاهیم پایه آشنا نیستید، پیش از ادامه هوک‌های وردپرس چیست، تفاوت اکشن و فیلتر در وردپرس و نحوه استفاده از add_filter را بخوانید. مکمل این مقاله مهم‌ترین فیلتر هوک‌های وردپرس، ساخت اکشن سفارشی، راهنمای حرفه‌ای کار با هوک‌ها و ساخت قابلیت اختصاصی با هوک‌ها است.

فیلتر سفارشی دقیقاً چیست؟

فیلتر سفارشی، یک «نقطه تبدیل داده» است که خودتان در کد افزونه یا قالب تعریف می‌کنید. هسته وردپرس ده‌ها فیلتر رسمی دارد (the_content، the_title، excerpt_length، pre_get_posts) که به شما اجازه می‌دهند داده را پیش از استفاده تغییر دهید. فیلتر سفارشی، همان مفهوم است، ولی برای داده‌های اختصاصی افزونه شما. مثال‌های طبیعی از دنیای واقعی:

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

سه تفاوت بنیادین با فیلترهای هسته:

  1. مالکیت: فیلتر هسته، بخشی از وردپرس است؛ فیلتر سفارشی، بخشی از افزونه شما. مسئولیت مستندسازی و پایداری آن با شماست.
  2. الزام بازگشت مقدار: callback فیلتر هسته همیشه مقدار را برمی‌گرداند. callback فیلتر سفارشی شما هم باید همیشه مقدار را برگرداند. اگر callback شما مقدار را برنگرداند، داده نابود می‌شود و نرم‌افزار شما با داده خالی مواجه می‌شود.
  3. الزام مستندسازی: فیلترهای هسته در مستندات رسمی وردپرس توضیح داده شده‌اند؛ فیلتر سفارشی شما فقط اگر مستندسازی کنید، قابل استفاده است.
فیلتر سفارشی، مثل ایستگاه بازرسی است؛ داده از آن عبور می‌کند، ولی اگر بازرس نداشته باشد، همان داده خام به مقصد می‌رسد. اگر ایستگاه خراب باشد، محموله نابود می‌شود.

سه گام ساخت فیلتر سفارشی

ساخت فیلتر سفارشی، سه گام ساده دارد:

  1. گام اول — تعریف نقطه تبدیل: در جایی از کد افزونه که داده تولید می‌شود، به‌جای استفاده مستقیم از داده، آن را از apply_filters() عبور دهید.
  2. گام دوم — پاس دادن پارامترها: داده اصلی را به‌عنوان پارامتر اول، و داده‌های زمینه‌ای را به‌عنوان پارامترهای بعدی پاس دهید.
  3. گام سوم — مستندسازی: در بالای خط apply_filters، با PHPDoc توضیح دهید که فیلتر چه داده‌ای را می‌گیرد، چه داده‌ای برمی‌گرداند و چه پارامترهای زمینه‌ای پاس می‌شود.

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

ساده‌ترین فیلتر سفارشی

حداقل یک فیلتر سفارشی، یک خط است:

// در افزونه شما، در جایی که داده تولید می‌شود
$message = apply_filters( 'myplugin_welcome_message', 'به سایت ما خوش آمدید!' );

echo esc_html( $message );

و مصرف آن در افزونه دیگر یا چایلد تم:

add_filter( 'myplugin_welcome_message', 'other_plugin_customize_welcome' );

function other_plugin_customize_welcome( $message ) {
    return $message . ' برای مشتریان ویژه، تخفیف ۱۰٪ فعال است.';
}

این دو خط، دقیقاً همان چیزی است که در ابتدای مقاله گفتم: افزونه شما را به یک نقطه قابل تنظیم تبدیل می‌کند. راهنمای نحوه قلاب‌زدن در نحوه استفاده از add_filter، استفاده درست از هوک‌ها، مهم‌ترین فیلتر هوک‌ها و تفاوت اکشن و فیلتر آمده است.

پاس دادن پارامترها به فیلتر سفارشی

فیلتر سفارشی معمولاً فقط یک مقدار را تغییر می‌دهد، ولی در پروژه‌های واقعی، callbackها به داده زمینه‌ای هم نیاز دارند. الگوی استاندارد: مقدار اصلی، پارامتر اول؛ داده زمینه‌ای، پارامترهای بعدی.

function myplugin_calculate_price( $product_id, $user_id ) {
    $product = wc_get_product( $product_id );
    if ( ! $product ) {
        return 0;
    }

    $base_price = (float) $product->get_price();

    /**
     * فیلتر قیمت نهایی محصول.
     *
     * @since 1.0.0
     *
     * @param float $base_price قیمت پایه محصول.
     * @param int   $product_id شناسه محصول.
     * @param int   $user_id    شناسه کاربری که قیمت را می‌بیند.
     * @return float قیمت نهایی.
     */
    $final_price = apply_filters( 'myplugin_final_price', $base_price, $product_id, $user_id );

    return max( 0, (float) $final_price );
}

و callback در افزونه دیگر:

add_filter( 'myplugin_final_price', 'myshop_apply_vip_discount', 10, 3 );

function myshop_apply_vip_discount( $price, $product_id, $user_id ) {
    if ( ! $user_id ) {
        return $price;
    }
    $tier = get_user_meta( $user_id, '_membership_tier', true );
    if ( 'gold' === $tier ) {
        $price = $price * 0.9;
    }
    return $price;
}

سه نکته در پاس دادن پارامترها: یک — پارامتر اول همیشه مقدار فیلترشده است. callbackها انتظار دارند اولین پارامتر، همان مقداری باشد که باید برگردانند. دو — داده زمینه‌ای را به‌صورت معنادار پاس دهید. اگر callback به شناسه محصول نیاز دارد، همان را پاس دهید؛ نه آرایه محصول کامل. سه — تعداد پارامترها را محدود نگه دارید. فیلتر با هفت پارامتر، برای callbackها گیج‌کننده است؛ اگر نیاز دارید، از یک آرایه معنادار استفاده کنید. راهنمای کامل در پارامترهای هوک وردپرس، Priority در هوک‌ها، کنترل ترتیب اجرای هوک‌ها، استفاده درست از هوک‌ها و راهنمای حرفه‌ای هوک‌ها آمده است.

فیلتر بدون پارامتر، صافیِ چای بدون قوری است؛ مقدار از آن عبور می‌کند ولی هیچ زمینه‌ای برای تصمیم‌گیری نیست.

مستندسازی فیلتر سفارشی با PHPDoc

الگوی استاندارد مستندسازی فیلتر سفارشی در وردپرس:

/**
 * فیلتر قیمت نهایی محصول، پس از اعمال همه محاسبات پایه.
 *
 * @since 1.0.0
 *
 * @param float $base_price قیمت پایه محصول، پیش از اعمال تخفیف و مالیات.
 * @param int   $product_id شناسه محصول در دیتابیس.
 * @param int   $user_id    شناسه کاربری که قیمت را می‌بیند؛ صفر برای مهمان.
 * @return float قیمت نهایی، به‌صورت عدد اعشاری مثبت.
 */
$final_price = apply_filters( 'myplugin_final_price', $base_price, $product_id, $user_id );

سه نکته در مستندسازی: یک — @since: نسخه‌ای که این فیلتر معرفی شده. اگر بعداً پارامتری اضافه کردید، در نسخه بعدی با @since دیگر توضیح دهید. دو — @param: نوع، نام و توضیح هر پارامتر، به‌همین ترتیب که در apply_filters پاس می‌شود. سه — @return: نوع و محدوده مقدار بازگشتی. الگوهای مشابه در ساختار استاندارد کدنویسی، استانداردهای کدنویسی وردپرس، اصول کدنویسی تمیز، ساختار فایل‌های افزونه استاندارد، استفاده از استانداردها در پروژه‌ها و ساختاربندی پروژه وردپرس آمده است.

نام‌گذاری فیلتر سفارشی: قواعد و اشتباهات

نام فیلتر سفارشی، سه قاعده دارد:

  1. پیشوند یکتا: نام فیلتر باید با پیشوند افزونه شما شروع شود. مثال: myplugin_final_price نه final_price.
  2. حروف کوچک و زیرخط: سبک استاندارد وردپرس. myplugin_final_price نه myPluginFinalPrice.
  3. نام معنادار و توصیفی: myplugin_final_price بهتر از myplugin_filter_1.

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

کجا apply_filters را قرار دهیم؟

انتخاب نقطه درست برای apply_filters، تفاوت بین فیلتر مفید و فیلتر بی‌فایده است. سه قاعده عملی:

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

// نامناسب
$total = $base + $tax;
update_option( 'last_total', $total );

// مناسب
$total = $base + $tax;
$total = apply_filters( 'myplugin_cart_total', $total, $cart_items, $user_id );
update_option( 'last_total', $total );

قاعده دوم — فیلتر را پیش از استفاده نهایی قرار دهید: اگر مقدار فیلترشده ذخیره می‌شود، فیلتر باید پیش از ذخیره اجرا شود. اگر مقدار فیلترشده نمایش داده می‌شود، فیلتر باید پیش از نمایش اجرا شود.

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

راهنمای تکمیلی در PHP امن در وردپرس، پاک‌سازی داده‌ها، اعتبارسنجی داده‌ها، توابع امنیت و پاک‌سازی و امنیت پروژه وردپرس آمده است.

ساختار کلاس‌محور برای فیلتر سفارشی

در افزونه‌های جدی، فیلترهای سفارشی را در یک کلاس نگه دارید:

class My_Plugin_Filters {
    /**
     * فیلتر قیمت نهایی محصول.
     *
     * @since 1.0.0
     *
     * @param float $base_price قیمت پایه.
     * @param int   $product_id شناسه محصول.
     * @param int   $user_id    شناسه کاربر.
     * @return float
     */
    public static function final_price( $base_price, $product_id, $user_id ) {
        return (float) apply_filters( 'myplugin_final_price', $base_price, $product_id, $user_id );
    }

    public static function cart_total( $total, $items, $user_id ) {
        return (float) apply_filters( 'myplugin_cart_total', $total, $items, $user_id );
    }

    public static function welcome_subject( $subject, $user_id ) {
        return (string) apply_filters( 'myplugin_welcome_email_subject', $subject, $user_id );
    }
}

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

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

سه اشتباه رایج در ساخت فیلتر سفارشی

فهرست کوتاه اما گران‌قیمت از اشتباهاتی که در کدهای بازبینی‌شده دیده‌ام:

فیلتر سفارشی، مثل قرارداد است؛ اگر نام و نوع داده شفاف نباشند، هر کس تفسیر خودش را می‌کند و نتیجه، آشفتگی است.

الگوهای حرفه‌ای: سه سطح عمق در ساخت فیلتر

در پروژه‌های خودم، سه سطح عمق برای فیلتر سفارشی می‌بینم:

سطح اول — فیلتر مقادیر ساده: تغییر یک رشته یا عدد. پرکاربردترین سطح. مثال:

$subject = apply_filters( 'myplugin_email_subject', 'سفارش شما ثبت شد', $order_id );

سطح دوم — فیلتر داده ساختاریافته: تغییر یک آرایه یا شیء. مثال:

$order_data = apply_filters( 'myplugin_order_data', $order_data, $order_id, $user_id );

سطح سوم — فیلتر پیش از پردازش سنگین: تغییر پارامترها یا نتایج یک فرآیند بزرگ. مناسب برای فیلترهای پیشرفته. مثال:

$query_args = apply_filters( 'myplugin_report_query_args', $query_args, $report_type );
$results    = $wpdb->get_results( $wpdb->prepare( $sql, $query_args ) );

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

ساخت فیلتر سفارشی برای افزونه‌های فروشگاهی

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

class My_Shop_Price_Filters {
    public static function init() {
        add_filter( 'woocommerce_product_get_price', array( __CLASS__, 'apply_custom_rules' ), 10, 2 );
    }

    public static function apply_custom_rules( $price, $product ) {
        $base = (float) $price;

        /**
         * فیلتر قیمت نهایی محصول در فروشگاه ما.
         *
         * @since 1.0.0
         *
         * @param float      $base    قیمت پایه.
         * @param WC_Product $product شیء محصول.
         * @return float
         */
        return (float) apply_filters( 'myshop_final_product_price', $base, $product );
    }
}

مصرف این فیلتر برای اعمال تخفیف VIP:

add_filter( 'myshop_final_product_price', 'myshop_apply_vip_discount', 10, 2 );

function myshop_apply_vip_discount( $price, $product ) {
    if ( ! is_user_logged_in() ) {
        return $price;
    }
    $tier = get_user_meta( get_current_user_id(), '_membership_tier', true );
    if ( 'gold' === $tier ) {
        $price = $price * 0.9;
    }
    return $price;
}

راهنمای کامل در هوک‌های ووکامرس، مدیریت سفارش‌های ووکامرس، تنظیم روش‌های پرداخت، تخفیف و کد تخفیف در ووکامرس، افزونه‌های کاربردی ووکامرس، افزایش سرعت فروشگاه و افزایش فروش فروشگاه آمده است.

فیلتر سفارشی در قالب: از چایلد به والد و برعکس

در قالب‌ها، فیلتر سفارشی معمولاً در دو سناریو به‌کار می‌آید:

سناریو اول — تغییر خروجی قالب والد توسط چایلد:

// در functions.php قالب والد
$footer_text = apply_filters( 'mytheme_footer_text', 'تمامی حقوق محفوظ است.' );

// در چایلد تم
add_filter( 'mytheme_footer_text', 'my_child_customize_footer' );

function my_child_customize_footer( $text ) {
    return '© ۱۴۰۵ - شرکت نمونه';‌
}

سناریو دوم — امکان سفارشی‌سازی تنظیمات قالب:

$items_per_page = apply_filters( 'mytheme_archive_items_per_page', 12 );
$items_per_page = max( 1, absint( $items_per_page ) );

راهنمای کامل در هوک‌ها در توسعه قالب، هوک‌های خروجی قالب، قالب چایلد چیست، توسعه با چایلد تم، ساختار فایل‌های قالب استاندارد، توسعه قالب از صفر و آماده‌سازی قالب برای فارسی آمده است.

دیباگ فیلتر سفارشی: ابزارها

وقتی فیلتر سفارشی کار نمی‌کند، چهار ابزار در پروژه‌های خودم استفاده می‌کنم:

  • Query Monitor: لیست تمام فیلترها با ترتیب و callback. راهنمای کامل در توابع دیباگ وردپرس.
  • error_log در callback: بررسی اینکه کد اجرا می‌شود یا نه. راهنما در دیباگ کد سفارشی وردپرس.
  • global $wp_filter: برای دیدن تمام callbackهای ثبت‌شده روی فیلتر. راهنما در دیباگ اکشن و فیلتر.
  • تست با priority پایین و بالا: اگر فیلتر شما در وسط زنجیره قرار می‌گیرد، از priority مناسب استفاده کنید.

یک تجربه میدانی: در پروژه‌ای، فیلتر سفارشی به‌نظر ساده کار نمی‌کرد. با global $wp_filter، کشف شد که افزونه‌ای دیگر فیلتر را با priority بالا ثبت کرده و مقدار را با یک محاسبه اشتباه جایگزین می‌کند. تنظیم priority، مشکل را حل کرد. راهنما در تست و دیباگ پروژه‌های وردپرس، دیباگ کد سفارشی و خطای Deprecated در PHP.

امنیت در فیلتر سفارشی: پنج قاعده طلایی

هر فیلتر سفارشی، یک نقطه ورود بالقوه است. پنج قاعده امنیتی الزامی:

  1. اعتبارسنجی مقدار بازگشتی: پس از apply_filters، مقدار را با توابع اعتبارسنجی، به نوع و محدوده مورد انتظار محدود کنید. راهنما در اعتبارسنجی داده‌ها.
  2. Escape خروجی پس از فیلتر: اگر مقدار فیلترشده در HTML نمایش داده می‌شود، با esc_html، esc_url یا esc_attr خروجی دهید. راهنما در پاک‌سازی داده‌ها.
  3. محدودسازی نوع بازگشتی: اگر فیلتر قیمت است، مقدار بازگشتی را با (float) و max( 0, ... ) محدود کنید تا مقدار منفی یا نامعتبر از callback معیوب عبور نکند. راهنما در PHP امن در وردپرس.
  4. مستندسازی نوع پارامترها: با PHPDoc نوع هر پارامتر را مشخص کنید تا callbackها به‌اشتباه داده حساس پاس ندهند. راهنما در ساختار استاندارد کدنویسی.
  5. بررسی دسترسی در callbackهای حساس: اگر callback فیلتری عملیات حساس انجام می‌دهد، current_user_can را چک کند. راهنما در نقش و دسترسی.

مباحث امنیتی تکمیلی در هوک‌های وردپرس و امنیت کد، امنیت پروژه وردپرس، امنیت وردپرس برای مبتدیان، افزونه‌های امنیتی وردپرس، نانس وردپرس، توابع امنیت و پاک‌سازی و امن‌سازی ورود ادمین آمده است.

فیلترهای سفارشی در پروژه‌های واقعی: سه مثال کامل

مثال اول — فیلتر گزارش‌های فروشگاهی:

class My_Shop_Reports {
    public static function get_sales_report( $period ) {
        $rows = self::query_sales( $period );

        /**
         * فیلتر ردیف‌های گزارش فروش.
         *
         * @since 1.0.0
         *
         * @param array  $rows   ردیف‌های گزارش.
         * @param string $period دوره گزارش (month, year).
         * @return array
         */
        return (array) apply_filters( 'myshop_sales_report_rows', $rows, $period );
    }
}

مثال دوم — فیلتر فهرست مطالب سری مقالات:

$series_items = apply_filters( 'myplugin_series_items', $series_items, $series_id );
$series_items = array_filter( $series_items, 'is_array' );

مثال سوم — فیلتر فهرست قابلیت‌های قابل نمایش به کاربر:

$allowed_features = apply_filters( 'myplugin_user_allowed_features', $default_features, $user_id );
$allowed_features = array_intersect( $allowed_features, array_keys( $all_features ) );

راهنمای کامل در کدنویسی اختصاصی افزونه، توسعه افزونه از صفر، ساخت قابلیت اختصاصی با هوک‌ها، توابع کوئری سفارشی، بهینه‌سازی کوئری‌ها و بهینه‌سازی کد وردپرس آمده است.

الگوی Registry Pattern برای فیلترهای سفارشی

در پروژه‌های بزرگ، تمام فیلترهای سفارشی را در یک نقطه ثبت کنید:

class My_Plugin_Filters {
    public static function init() {
        add_filter( 'myplugin_final_price', array( __CLASS__, 'default_discount' ), 10, 3 );
        add_filter( 'myplugin_cart_total', array( __CLASS__, 'round_total' ), 20, 3 );
    }

    public static function default_discount( $price, $product_id, $user_id ) {
        return $price;
    }

    public static function round_total( $total, $items, $user_id ) {
        return round( (float) $total, 2 );
    }
}

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

فیلترهای سفارشی در افزونه‌های آموزشی و LMS

در سایت‌های آموزشی، فیلتر سفارشی برای منطق کسب‌وکار ضروری است:

یک — فیلتر محتوای درس پیش از نمایش:

$lesson_content = apply_filters( 'myplugin_lesson_content', $lesson_content, $lesson_id, $user_id );
$lesson_content = wp_kses_post( $lesson_content );

دو — فیلتر نمره نهایی دانشجو:

$final_score = apply_filters( 'myplugin_final_quiz_score', $raw_score, $quiz_id, $user_id );
$final_score = max( 0, min( 100, (int) $final_score ) );

سه — فیلتر متن گواهی پایان دوره:

$certificate_text = apply_filters( 'myplugin_certificate_text', $default_text, $user_id, $course_id, $certificate_id );
$certificate_text = wp_kses_post( $certificate_text );

راهنمای کامل در هوک‌های مدیریت کاربران، هوک‌های ورود و ثبت‌نام، کار با User Meta، توابع نقش و دسترسی، افزونه‌های سایت آموزشی، قالب آموزشی و ساخت قابلیت اختصاصی با هوک‌ها آمده است.

فیلترهای سفارشی در افزونه‌های گزارش‌گیری

در پروژه‌های گزارش‌گیری، فیلتر سفارشی امکان سفارشی‌سازی گزارش‌ها را فراهم می‌کند:

یک — فیلتر ستون‌های گزارش:

$columns = apply_filters( 'myplugin_report_columns', array(
    'id'    => 'شناسه',
    'title' => 'عنوان',
    'total' => 'مجموع',
), $report_type );
$columns = array_intersect_key( $columns, $allowed_columns );

دو — فیلتر شرط‌های کوئری گزارش:

$where = apply_filters( 'myplugin_report_where', $default_where, $report_type );
$where = wp_kses( $where, array() ); // حذف کاراکترهای مخرب

سه — فیلتر خروجی گزارش (برای CSV، PDF، Excel):

$rows = apply_filters( 'myplugin_report_rows', $rows, $report_type );
$rows = array_map( 'array_filter', $rows );

راهنمای تکمیلی در توابع کوئری سفارشی، بهینه‌سازی کوئری‌ها، توابع کار با فایل، بهینه‌سازی کوئری‌های MySQL، تأثیر دیتابیس بر سرعت سایت، بهینه‌سازی کد وردپرس و کاهش مصرف منابع هاست آمده است.

فیلتر سفارشی، در پروژه‌های گزارش‌گیری، مثل کلید تنظیم است؛ بدون آن، هر سفارشی‌سازی یک پروژه کوچک جداگانه می‌شود.

جمع‌بندی

ساخت فیلتر سفارشی در وردپرس، سه گام ساده دارد: تعریف نقطه تبدیل با apply_filters، پاس دادن پارامترها و مستندسازی با PHPDoc. سه اصل را در پایان تاکید می‌کنم: اول، فیلتر سفارشی را به‌عنوان پلتفرم ببینید، نه قابلیت جانبی. دوم، پیشوند یکتا و نام معنادار را جدی بگیرید تا با دیگران تعارض نکند. سوم، پس از فیلتر، مقدار را اعتبارسنجی و escape کنید تا داده آلوده به خروجی نرسد.

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