بنية خطافات ووردبريس: شرح الإجراءات مقابل المرشحات

كل إضافة ووردبريس تقوم بأحد أمرين: تنفيذ تعليمات برمجية في لحظة معينة (إجراء)، أو تعديل قيمة قبل استخدامها (مرشح). هذا كل شيء. يعتمد نظام الإضافات بأكمله في ووردبريس على هذا التمييز.

فهم الفرق - ومتى تستخدم كل منهما - هو ما يميز الإضافات التي تعمل عن الإضافات التي تسبب مشاكل.

الإجراءات: فعل شيء في وقت معين

خطاف الإجراء هو إشارة يرسلها ووردبريس (أو إضافة أخرى) في لحظة معينة. تقوم بإرفاق دالة بهذه الإشارة، وتعمل دالتك عندما يتم إطلاق الإشارة.

add_action( 'wp_enqueue_scripts', 'my_plugin_load_assets' );

function my_plugin_load_assets() {
    wp_enqueue_style( 'my-plugin', plugin_dir_url( __FILE__ ) . 'style.css' );
    wp_enqueue_script( 'my-plugin', plugin_dir_url( __FILE__ ) . 'script.js', ['jquery'], '1.0', true );
}

يتم إطلاق wp_enqueue_scripts عندما يستعد ووردبريس لتحميل الأصول للواجهة الأمامية. ربطها هو الطريقة الصحيحة لتحميل CSS و JS - وليس إسقاط علامات <script> مباشرة في القوالب.

خطافات الإجراءات الشائعة التي ستستخدمها باستمرار:

• init — يتم تشغيله مبكرًا، وهو جيد لتسجيل أنواع المشاركات والتصنيفات
• wp_enqueue_scripts — تحميل أصول الواجهة الأمامية
• admin_enqueue_scripts — تحميل أصول المسؤول
• save_post — يتم تشغيله عند حفظ مشاركة، وهو جيد لمعالجة الحقول المخصصة
• wp_ajax_{action} — معالجة طلبات AJAX من المستخدمين المصادق عليهم
• wp_ajax_nopriv_{action} — معالجة طلبات AJAX من المستخدمين غير المسجلين

المرشحات: تعديل قيمة قبل استخدامها

يمنحك خطاف المرشح قيمة، ويسمح لك بتعديلها، ويتوقع منك إرجاع النسخة المعدلة. يستخدم ووردبريس بعد ذلك القيمة المعدلة بدلاً من الأصلية.

add_filter( 'the_content', 'my_plugin_append_cta' );

function my_plugin_append_cta( $content ) {
    if ( ! is_single() ) {
        return $content;
    }
    $cta = '<div class="post-cta">Ready to try PAGEnza? <a href="#">Get started free →</a></div>';
    return $content . $cta;
}

القاعدة الحاسمة: ارجع دائمًا شيئًا ما من المرشح. إذا نسيت return، ستصبح القيمة فارغة وقد كسرت كل ما كان يستخدمها.

خطافات المرشحات الشائعة:

• the_content — محتوى المشاركة قبل العرض
• the_title — عنوان المشاركة
• wp_nav_menu_items — HTML لقائمة التنقل
• upload_mimes — أنواع الملفات المسموح بتحميلها
• plugin_action_links_{plugin-file} — الروابط المعروضة في صفحة قائمة الإضافات

كيف يستخدم PAGEnza AI الخطافات

عندما يقوم Plugin Builder بإنشاء إضافة، فإنه ينظم التعليمات البرمجية حول فئة تحتوي على دوال مرتبطة بالخطافات في المُنشئ. هذا النمط يتجنب تضارب أسماء الدوال العامة ويحافظ على تنظيم التعليمات البرمجية.

class My_Plugin {
    public function __construct() {
        add_action( 'init', [ $this, 'register_post_type' ] );
        add_action( 'wp_enqueue_scripts', [ $this, 'load_assets' ] );
        add_filter( 'the_content', [ $this, 'append_content' ] );
    }

    public function register_post_type() { /* ... */ }
    public function load_assets() { /* ... */ }
    public function append_content( $content ) {
        // always return
        return $content;
    }
}

new My_Plugin();

يفحص فحص الأمان تحديدًا أن معالجات AJAX تتضمن فحصًا للرمز (nonce) وفحصًا للقدرة قبل القيام بأي شيء:

add_action( 'wp_ajax_my_action', [ $this, 'handle_ajax' ] );

public function handle_ajax() {
    // Security: verify nonce
    check_ajax_referer( 'my_nonce_action', 'nonce' );

    // Security: verify permissions
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_send_json_error( 'Insufficient permissions', 403 );
    }

    // Now safe to process
    $data = sanitize_text_field( $_POST['data'] ?? '' );
    wp_send_json_success( [ 'result' => $data ] );
}

يتم تمييز أي من هذين العنصرين كقضية أمنية ويمنع إصدار الإضافة.

الأولوية وقائمة انتظار الخطافات

عندما يتم ربط دوال متعددة بنفس الخطاف، فإنها تعمل بترتيب الأولوية (رقم أقل = يعمل أولاً). الأولوية الافتراضية هي 10.

add_action( 'init', 'runs_first', 5 );
add_action( 'init', 'runs_second', 10 );   // default
add_action( 'init', 'runs_last', 20 );

هذا مهم عندما تحتاج إضافتك إلى العمل قبل أو بعد تعليمات برمجية لإضافة أخرى. إذا كنت تعدل شيئًا تعدله إضافة أخرى أيضًا، فإن الأولوية تتحكم في من يفوز.

نمط شائع: إذا كنت تتجاوز مرشحًا للقالب، استخدم الأولوية 20 أو أعلى للتأكد من أنك تعمل بعد تعليمات القالب البرمجية.

إزالة الخطافات

يمكنك إزالة خطاف أضافه شخص آخر - بما في ذلك خطافات القوالب والإضافات:

remove_action( 'wp_head', 'wp_generator' );  // يزيل إصدار WP من <head>
remove_filter( 'the_content', 'wpautop' );   // يزيل التفاف الفقرات التلقائي

المشكلة: يمكنك فقط إزالة خطاف إذا قمت باستدعاء remove_action/remove_filter بعد تشغيل add_action/add_filter الأصلي. هذا يعني عادةً ربط إزالتك بخطاف لاحق.