شرح الخطافات في ووردبريس WordPress Hooks

تُعتبر الخطافات في ووردبريس (WordPress Hooks) من أبرز الميزات التي تسهم في تمكين مطوري ووردبريس من إنشاء قوالب وإضافات مخصصة، أو تعديل سلوك قالب أو إضافة معينة، أو حتى تغيير طريقة عمل ووردبريس بشكل عام.

تتمثل الخطافات في دوال (Functions) تحتوي على تعليمات برمجية قادرة على تنفيذ إجراءات معينة، أو تصفية وتعديل بيانات محددة داخل ووردبريس.

في هذا المقال، سنستعرض مفهوم الخطافات في ووردبريس، ونتعرف على أنواعها وآلية عملها. ومن المهم الإشارة إلى أن هذا الموضوع يعد من الأساسيات التي ينبغي على أي مطور قوالب أو إضافات في ووردبريس إتقانها كجزء من عملية تطوير المنصة.

ما هي الخطافات في ووردبريس

في أي موقع ووردبريس، هناك ثلاثة عناصر رئيسية تتعاون معًا لتشكيل وعرض صفحات الموقع بالشكل النهائي. هذه العناصر هي نواة ووردبريس (WordPress Core)، وقالب ووردبريس، والإضافات الخارجية المفعلة.

تقوم نواة ووردبريس بتشغيل الوظائف الأساسية للموقع، بينما تضيف الإضافات والقوالب ميزات ووظائف إضافية، وتتحكم في مظهر الموقع، حيث يعتمد كلاهما بشكل كبير على الخطافات.

تتمثل المهمة الأساسية للخطافات في ووردبريس في تمكين المطورين من تعديل أو إضافة ميزات جديدة إلى الوظائف الافتراضية لووردبريس دون الحاجة إلى تغيير الملفات الأساسية للنظام.

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

يحتوي نواة ووردبريس على أكثر من 2200 خطاف افتراضي، مما يتيح للمطورين تحديد المواقع التي يرغبون في ربط وتشغيل التعليمات البرمجية المخصصة فيها. يمكنك الاطلاع على قائمة بجميع هذه الخطافات ومتى تعمل من خلال الرابط التالي.

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

تعمل واجهة برمجة تطبيقات الإضافات (Plugin API) على تفعيل وظائف الخطافات في ووردبريس. يمكنك استخدام الخطافات من خلال استدعاء دوال ووردبريس المحددة، المعروفة بدوال الخطاف (Hook Functions)، والتي تُستدعى في حالات معينة تحدث أثناء تشغيل ووردبريس.

من خلال دوال الخطافات، يمكنك تجميع التعليمات البرمجية الخاصة بك ضمن تابع أو دالة رد النداء (Callback Function) وربطها أو تسجيلها بأي خطاف.

يمكنك استخدام دوال رد النداء إما كدوال PHP عادية، أو كدوال ووردبريس افتراضية، أو يمكنك كتابة دوال برمجية مخصصة حسب احتياجاتك. (يمكنك زيارة الصفحة التالية في الدليل الرسمي لمطوري ووردبريس للاطلاع على مزيد من التعليمات حول الدوال البرمجية في ووردبريس).

بمجرد ربط الخطاف بدالة رد النداء، ستُنفذ هذه الدالة في كل مرة يحدث فيها الخطاف، مما يتيح لمطوري ووردبريس إضافة ميزات جديدة أو تعديل الميزات الافتراضية في ووردبريس.

أنواع الخطافات في ووردبريس

يوفر نظام ووردبريس نوعين من الخطافات:

1. خطافات الإجراءات (Action Hooks): تتيح للمطورين تنفيذ مهام أو أوامر معينة في نقاط محددة مسبقًا خلال فترة تشغيل ووردبريس.
2. خطافات المرشحات (Filter Hooks): تمكن من تعديل أي بيانات يتم معالجتها بواسطة ووردبريس وإرجاع هذه البيانات المعدلة.

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

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

كيف تعمل الخطافات في ووردبريس؟

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

تنقسم التوابع البرمجية المستخدمة في نظام الخطافات إلى ثلاثة أنواع:

1. الخطافات: وتشمل نوعين، وهما الإجراءات (Action hooks) والفلاتر (Filter hooks). هذه الخطافات موجودة بالفعل في كود ووردبريس، ولا تقوم بأي وظيفة بمفردها، بل تنتظر أن يتم تفعيلها بواسطة دوال الخطافات.
2. دوال الخطافات: تتضمن دوال الإجراءات (Action functions) ودوال الفلاتر (Filter functions)، وتستخدم لتسجيل الخطافات وربطها بدوال رد النداء (Callback functions).
3. دوال رد النداء: تحتوي على الكود المخصص الذي يرغب المطور في تنفيذه عند تفعيل الخطاف المرتبط بها.

ملاحظة:

لا يهم ترتيب استخدام هذه الدوال في كودك، حيث يمكنك البدء بتعريف دالة رد النداء وكتابة الكود الخاص بها، ثم تسجيلها وربطها مع الخطاف المطلوب. ومع ذلك، يُفضل أن تكون هذه العناصر قريبة من بعضها في الكود لتسهيل فهم العلاقة بينها.

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

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

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

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

على سبيل المثال، يمكنك تعديل النص في منشور معين عن طريق ربط دالة رد النداء بخطاف الإجراء publish_post، وتغيير محتوى المنشور عند حفظه في قاعدة البيانات كما يلي:

// define the callback function to change the text
function change_text_callback() { 
    // add the code to change text here
}

// hook in to the 'publish_post' action with the add_action() function
add_action( 'publish_post', 'change_text_callback' );

يمكنك أيضًا تسجيل دالة رد نداء بديلة، ولكن هذه المرة باستخدام خطاف الفلترة the_content، وذلك لتعديل محتوى المقال قبل عرضه في المتصفح، كما هو موضح أدناه:

// define the callback function to modify the text
function change_text_callback( $content ) { 
    // add the code to change text here and then return it 
    return $filtered_content;
}

// hook in to 'the_content' filter with the add_filter() function
add_filter( 'the_content', 'change_text_callback');

هل تشعر أن الأمور معقدة ومتشابكة؟ لا داعي للقلق، في الفقرات القادمة سنقدم لك توضيحات حول الخطافات وسنرفق أمثلة عملية تساعدك على فهم الموضوع بشكل أفضل.

خطافات الإجراءات في ووردبريس (Action Hooks)

يتم تعريف خطافات الإجراءات Action Hooks في ووردبريس من خلال الدالة do_action اللتي تأخذ الشكل التالي:

do_action( 'action_name', [optional_arguments] );

إليك النص المعاد كتابته:

حيث أن:

• action_name هو سلسلة نصية تمثل اسم الحدث أو الإجراء الذي سيحدث في الموقع، وعادة ما يكون اسمًا معبرًا يوضح طبيعة هذا الحدث.
• [optional_arguments] هو حقل للمتغيرات أو الوسائط الاختيارية التي يمكن تمريرها إلى دالة رد النداء (callback). وإذا لم يتم تحديد قيمة لهذا الحقل، ستكون القيمة الافتراضية فارغة.

على سبيل المثال، إليك خطاف الإجراء التالي:

do_action( 'wp_head' )

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

أما بالنسبة لخطاف الإجراء التالي، فهو…

do_action( 'wp_footer' )

هو دالة تمثل خطافًا يتيح لك تشغيل كود مخصص في كل مرة يتم فيها عرض التذييل (Footer) في موقع ووردبريس الخاص بك، ولا يحتوي هذا الخطاف على أي وسائط أو معلمات إضافية.

أهم دوال خطافات الإجراءات

في هذه الفقرة، نستعرض أبرز الدوال البرمجية المستخدمة مع خطافات الإجراءات في ووردبريس.

الدالة add_action
تُعتبر الدالة add_action() من أكثر دوال خطافات الإجراءات شيوعًا، حيث تُستخدم بشكل أساسي لربط دالة رد النداء الخاصة بك بخطاف إجراء معين. من خلال ذلك، نوجه ووردبريس لتنفيذ كود دالة رد النداء عند حدوث هذا الإجراء. وتقبل هذه الدالة وسيطين: الأول هو اسم الإجراء الذي ترغب في تنفيذ الكود عند حدوثه، والثاني هو دالة رد النداء التي تحتوي على هذا الكود.

add_action( 'hook_action_name', 'callback_function');

على سبيل المثال لتنفيذ دالة wporg_callback () عند وقوع الخطاف init نكتب الكود التالي:

add_action( 'init', 'wporg_callback' );
function wporg_callback() {
    // اكتب هنا الكود الذي ترغب بتنفيذه
}

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

1. الأولوية (priority): هي عدد صحيح موجب، وقيمتها الافتراضية هي 10. هذا البرامتر يحدد أولوية تنفيذ دالة رد النداء المرتبطة بالخطاف، حيث كلما انخفضت قيمة الأولوية، زادت أولوية تنفيذ الدالة. يعتبر برامتر الأولوية مهمًا للمطورين الذين يرغبون في ربط عدة دوال رد نداء بخطاف معين، حيث يساعدهم في تجنب النتائج غير الصحيحة الناتجة عن ترتيب تنفيذ هذه الدوال. على سبيل المثال، إذا قمنا بربط ثلاث دوال رد نداء بخطاف معين كما يلي:

• foo1() مع أولوية 11
• foo2() مع أولوية 10
• foo3() مع أولوية 9

فإنه عند حدوث الخطاف، سيتم تنفيذ الدالة foo3() أولاً، تليها foo2()، ثم foo1(). وإذا كانت جميع الدوال تحمل نفس الأولوية، فسيتم تنفيذها بالترتيب الذي تم ربطها به في الكود.

2. عدد البرامترات (Accepted args): بشكل افتراضي، تستقبل أي دالة رد نداء مرتبطة بالخطاف من خلال add_action() وسيطًا واحدًا فقط. ومع ذلك، قد تحتاج أحيانًا إلى تمرير وسائط إضافية إلى دالة رد النداء. لذلك، يمكن للدالة add_action() أن تقبل وسائط اختيارية إضافية تتيح لك تحديد عدد الوسائط المطلوبة.

على سبيل المثال، الخطاف comment_post يتم تنفيذه مباشرة بعد أن يقوم ووردبريس بإضافة تعليق على مقال في قاعدة البيانات. إذا لم تقم بتحديد برامتر عدد الوسائط لهذا الخطاف، فسيتم تمرير قيمة واحدة فقط إلى دالة رد النداء المرتبطة به، وهي معرف التعليق comment_ID.

إذا كنت ترغب في إضافة برامتر إضافي يمثل قيمة منطقية comment_approved، حيث تأخذ القيمة 1 في حال الموافقة على التعليق و0 في حال رفضه كتعليق مزعج، يمكنك تمرير القيمة 2 لعدد برامترات الخطاف كما يلي:

add_action( 'comment_post', 'show_message_function', 10, 2 );

إذا قمت بتحديد عدد البرامترات إلى 2، فهذا يعني أنه يمكنك الآن تمرير قيمتين إلى الدالة، وهما: comment_ID و comment_approved. وذلك سيمكنك من تنفيذ كود معين داخل هذه الدالة فقط عند التأكد من أن التعليق مقبول وليس تعليقًا مزعجًا، كما هو موضح أدناه:

function show_message_function( $comment_ID, $comment_approved) {
    // check whether a comment is approved with the second parameter
    if( 1 === $comment_approved ){
        // قم هنا بكتابة الكود الذي تريد تنفيذه فقط في حال كون التعليق مقبول
    }
}

بالطبع، يمكنك تمرير أي عدد من المعاملات أو الوسطاء حسب احتياجاتك وكودك الخاص. لكن تأكد من أن كل من دالة add_action() ودالة رد النداء (callback function) تحتويان على نفس عدد الوسطاء.

الدالة do_action

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

يمكنك، كمطور ووردبريس، استخدام هذه الدالة لإنشاء خطاف إجراء مخصص خاص بك من خلال تحديد اسم الخطاف كوسيط للدالة. كما يمكنك أيضًا تمرير برامترات إضافية بشكل اختياري إذا كنت ترغب في استخدام وظائف رد النداء الخاصة بك، كما هو موضح أدناه:

do_action( 'action_name', [argument1], [argument2] );

الدالة do_action_ref_array:

تعمل هذه الدالة بطريقة مشابهة للدالة do_action()، ولكن يتم تمرير الوسائط إليها عبر مصفوفة. تُعتبر هذه الدالة مفيدة في حال كانت الوسائط لديك موجودة بالفعل في مصفوفة، أو عندما تحتاج إلى تمرير عدد كبير من الوسائط إلى الدالة.

$arguments_array = array( 'arg_1', 'foo', true, 'arg_4' );
do_action_ref_array( 'example_action', $arguments_array );

الدالة has_action:

تقوم دالة has_action بالتحقق مما إذا كان هناك خطاف معين مرتبط بدالة معينة. تأخذ هذه الدالة وسيطين: الأول هو اسم خطاف الإجراء (action_name)، والثاني هو وسيط اختياري يمثل اسم دالة رد النداء المراد التحقق منها (function_to_check).

إذا قمت بتمرير كلا الوسيطين، ستعيد الدالة القيمة المنطقية “خطأ” (false) إذا لم تكن دالة رد النداء المحددة مسجلة بخطاف الإجراء المعني. أما إذا قمت بتمرير الوسيط الأول فقط، فستعيد القيمة المنطقية “صحيح” (true) إذا كان هناك أي دالة رد نداء مرتبطة بالوسيط الأول الذي يمثل اسم الخطاف، و”خطأ” (false) في حال عدم وجودها.

has_action( 'action_name', 'function_to_check' );

الدالة did_action:

تُستخدم هذه الدالة لتحديد عدد مرات حدوث أي خطاف (Hook) خلال تشغيل الموقع. حيث تُرجع قيمة صحيحة تمثل عدد مرات وقوع هذا الخطاف في موقعك.

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

add_action('example_action', 'example_callback_function'
function example_callback_function() {
    if( did_action( 'example_action' ) === 1 ) {
    // هنا اكتب الكود الذي تريد تنفيذه عند وقوع الخطاف 'example_action' للمرة الأولى فقط 
    }
}

دالة remove_action

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

remove_action( 'action_name', 'function_to_be_removed', [priority] );

لكي تتمكن من استخدام هذه الدالة، يجب أن يتطابق كل من الوسيطين function_to_be_removed، الذي يمثل دالة رد النداء التي ترغب في فك ارتباطها، ووسيط الأولوية priority مع قيم وسطاء الدالة التي يتم من خلالها الربط add_action().

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

على سبيل المثال، تستخدم إضافة ووكوميرس هذه الدالة لإزالة الصورة المصغرة الافتراضية للمنتج من الصفحة الرئيسية للمتجر، وذلك من خلال الكود التالي:

remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail', 10 );

الدالة remove_all_action

تُستخدم هذه الدالة لإزالة جميع دوال رد النداء المرتبطة بخطاف إجراء محدد. كل ما علينا فعله هو تمرير اسم الخطاف المطلوب كوسيط. بالإضافة إلى ذلك، يمكن تمرير وسيط اختياري يمثل الأولوية كما هو موضح أدناه.

remove_all_actions( 'action_name', [priority] );

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

الدالة doing_action

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

if ( doing_action( 'action_name' ) ) {
    // execute your code here
}

يمكن استخدام هذه الدالة بدون وسطاء، وفي هذه الحالة ستعيد القيمة “صحيح” (true) إذا حدث أي خطأ أثناء تشغيل الموقع، كما هو موضح أدناه.

if ( doing_action() ) {
    // the code here is run when any action is fired
}

خطافات الفلترة في ووردبريس (Filter Hooks)

تُعرَّف خطافات الفلترة (Filter Hooks) في نواة ووردبريس من خلال الدالة apply_filters، والتي تأتي بالشكل التالي:

apply_filters( 'filter_name', 'value_to_be_filtered', [optional_arguments] );

حيث أن:

• filter_name: هو سلسلة نصية تمثل اسم الفلتر أو المرشح.
• value_to_be_filtered: هو متغير يمثل القيمة التي ينبغي تعديلها أو فلترتها وإرجاعها.
• [Optional_arguments]: هي وسائط يمكن تمريرها بشكل اختياري إلى الفلتر.

يستخدم نظام ووردبريس العديد من الفلاتر المدمجة لتعديل البيانات المستخدمة في وظائفه المختلفة. على سبيل المثال، يمكن استخدام خطاف الفلترة التالي:

apply_filters( 'admin_footer_text' , string $text )

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

أهم دوال خطافات الفلترة في ووردبريس

في هذه الفقرة، نستعرض أبرز الدوال البرمجية المستخدمة مع خطافات الفلترة في ووردبريس.

الدالة add_filter
تُعتبر الدالة add_filter() واحدة من أكثر دوال خطافات الفلترة شيوعًا واستخدامًا. تُستخدم هذه الدالة لربط دالة رد النداء بخطاف فلترة محدد (filter hook). ولتنفيذ ذلك، نقوم بتمرير وسيطين إلى هذه الدالة، وهما اسم الفلتر والدالة التي نرغب في ربطها بهذا الفلتر، كما هو موضح أدناه:

add_filter( 'hook_filter_name', ;'callbak_function')

على غرار الدالة add_action()، يمكن لهذه الدالة أيضًا أن تستقبل بشكل اختياري وسيطين إضافيين هما:

• الأولوية (priority): وهو عدد صحيح يحدد أولوية تنفيذ الدوال المرتبطة، بحيث يتم تشغيل كل دالة رد نداء وفق ترتيب أولويتها.
• عدد الوسطاء (Accepted args): وهو عدد صحيح يمكنك تمريره للدالة إذا كنت بحاجة إلى تمرير عدد إضافي من الوسائط لدالة رد النداء المرتبطة بالفلتر (حيث تقبل دالة رد النداء وسيطًا واحدًا بشكل افتراضي).

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

add_filter( 'hook_filter_name', 'example_callback' );
function example_callback( $example ) {
    // Maybe modify $example in some way.
    return $example;
}

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

has_filter( 'filter_name', 'function_to_check' );

إذا قمت بتمرير وسيط واحد فقط للدالة has_filter، فستعيد القيمة المنطقية “صحيح” (True) إذا كان الفلتر filter_name مرتبطًا بأي دالة. أما إذا قمت بتمرير وسيطين، فستعيد عددًا صحيحًا يمثل أولوية الدالة المرتبطة بهذا الفلتر، بشرط أن تكون دالة رد النداء المعنية مرتبطة بالفلتر المحدد، وفي حالة عدم ارتباطها، ستعيد القيمة المنطقية “خطأ” (False).

الدالة application_filters

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

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

apply_filters( 'filter_name', 'value_to_filter', [argument1], [argument2] );

الدالة application_filters_ref_array

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

// an example array
$arguments_array = array( 'some_value', 'foo', false, 'another_value' );

apply_filters_ref_array( 'example_filter', $arguments_array );

الدالة current_filter

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

function example_callback() {
    echo current_filter(); // 'the_title' will be echoed
    return
}
add_filter( 'the_title', 'example_callback' );

الدالة remove_filter

تعمل هذه الدالة على إزالة دالة رد النداء المرتبطة بخطاف الفلتر المحدد كوسيط. وهي تشبه في وظيفتها الدالة remove_action المستخدمة مع خطافات الإجراءات.

يمكن الاستفادة من هذه الدالة لحذف الدوال الافتراضية المسجلة في ووردبريس المرتبطة بخطاف فلتر معين، مما يتيح لك ربط دوال رد النداء الخاصة بك عند الحاجة.

remove_filter( 'filter_name', 'function_to_be_removed', [priority] );

لإلغاء ربط دالة رد النداء المرتبطة بفلتر معين، يجب أن تتطابق كل من الوسيطين function_to_be_removed و priority مع الوسيطين المستخدمين عند ربط دالة رد النداء بهذا الفلتر.

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

// access the class variable first, and then remove the filter through it
global $some_class;

remove_filter( 'the_content', array($some_class, 'class_filter_callback') );

على سبيل المثال، تستخدم إضافة WooCommerce دالة رد نداء تُدعى wc_lostpassword_url() المرتبطة بخطاف الفلترة lostpassword_url، وذلك لإعادة توجيه المستخدمين الذين ينقرون على رابط “هل نسيت كلمة مرورك؟” إلى صفحة مخصصة برابط URL خاص، مثل:

www.domain/my-account/lost-password

بدلاً من توجيههم إلى عنوان URL الافتراضي المستخدم لتسجيل الدخول إلى ووردبريس:

www.domain/wp-login.php

إذا كنت ترغب في إعادة تعيين هذه الدالة وإرسال المستخدمين إلى صفحة استرداد كلمة المرور الافتراضية أو إلى أي صفحة مخصصة أخرى، يمكنك إزالة ربط دالة رد النداء wc_lostpassword_url بالفلتر كما يلي:

remove_filter( 'lostpassword_url', 'wc_lostpassword_url', 10 ); 

الدالة remove_all_filter
تعمل هذه الوظيفة على إزالة جميع دوال رد النداء المرتبطة بخطاف فلتر معين، وذلك بطريقة مشابهة لدالة remove_all_actions المستخدمة في فلاتر الإجراءات.

remove_all_filters( 'filter_name', [priority] );

على سبيل المثال، تقوم إضافة Advanced Excerpt بإلغاء جميع الدوال الافتراضية المرتبطة بفلتر _excerpt وفلتر get_the_excerpt، ثم تقوم بعد ذلك بربط دوال رد النداء الخاصة بها بهذه الفلاتر.

if ( ! has_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) ) ) {
    remove_all_filters( 'get_the_excerpt' ); 
    remove_all_filters( 'the_excerpt' ); 
    add_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) );
}

الدالة do_filter
تقوم دالة الفلتر هذه بالتحقق مما إذا كان الفلتر المحدد يعمل حاليًا. إذا كان الخطاف قيد التنفيذ، فإنها تعيد القيمة المنطقية True، أما إذا لم يكن كذلك، فتعيد القيمة False.

if ( doing_filter( 'save_post' ) ) {
    // run your code here
}

شرح الكود البرمجي للإضافة:

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

1. خطاف الإجراء login_enqueue_scripts: يُستخدم لإضافة تنسيقات أو سكربتات إلى صفحة تسجيل الدخول في ووردبريس. قمنا بربطه بدالة رد النداء my_login_logo، التي تعمل على استبدال صورة الشعار الافتراضية للوردبريس بشعار موقعنا، والذي تم حفظه في مجلد images داخل مجلد الإضافة.
2. خطاف الفلترة login_headerurl: يُستخدم لتغيير عنوان URL للشعار المعروض في صفحة تسجيل الدخول. قمنا بربطه بدالة رد النداء my_login_logo_url، التي تعيد رابط الصفحة الرئيسية لموقعنا.
3. خطاف الفلترة login_headertext: يُستخدم لتخصيص نص رابط صفحة تسجيل الدخول، حيث قمنا بربطه بدالة رد النداء my_login_logo_url_title، التي تعرض اسم موقعنا “wpar”.

للاستفادة من هذه الخطافات في ووردبريس ، قمنا بتسجيل كل خطاف بدالة مناسبة (حيث نربط خطاف الإجراء بدالة add_action وخطاف الفلترة بدالة add_filter)، ثم مررنا دالة رد النداء كمرجع ليتم تنفيذها عند وقوع الخطاف.

الخطوة التالية هي تعريف كل دالة من دوال رد النداء وكتابة الكود المطلوب داخلها. يجب أن نلاحظ أن هذه الدوال ستنفذ تلقائيًا عند حدوث كل خطاف مرتبط بها.

• الدالة my_login_logo(): في هذه الدالة، كتبنا كودًا برمجيًا لاستبدال شعار ووردبريس باستخدام خاصية CSS للصورة الخلفية، حيث استخدمنا الدالة content_url() لاسترداد مسار مجلد المحتوى، ثم أضفنا بقية مسار صورة الشعار.
• الدالة my_login_logo_url(): في هذه الدالة، كتبنا كودًا يعيد رابط URL للصفحة الرئيسية للموقع الحالي باستخدام الدالة الجاهزة home_url().
• الدالة my_login_logo_url_title(): يحتوي رابط الشعار بشكل افتراضي على النص “يعمل بواسطة ووردبريس”. في هذه الدالة، كتبنا كودًا لتغيير نص هذا الرابط إلى “الدليل العربي لتعلم ووردبريس”، مما يوضح للزائر الغرض من الرابط قبل النقر عليه.

الآن، سيقوم نظام ووردبريس بتشغيل هذه التوابع وتنفيذ كافة التعليمات البرمجية التي كتبناها في كل مرة يحدث فيها الخطاف أثناء تشغيل موقعنا.

وبذلك، نكون قد انتهينا من تخصيص صفحة تسجيل الدخول إلى ووردبريس، حيث قمنا بتغيير شعار تسجيل الدخول وعنوان URL للشعار ونص الشعار باستخدام الخطافات ضمن إضافة خاصة بنا، دون الحاجة لتعديل كود ووردبريس نفسه.

مصادر هامة لتعلم خطافات ووردبريس بشكل احترافي

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

يوفر ووردبريس آلاف الخطافات التي تهدف إلى تسهيل عملك، وكل ما عليك فعله هو التعرف عليها وربط كودك الخاص بها واستخدامها بشكل مثالي لتخصيص موقعك. إليك بعض المصادر المفيدة التي ستساعدك في تعلم المزيد عن الخطافات في ووردبريس وتحديد الخطاف المثالي لاحتياجاتك.

مرجع 1: هذا الرابط يشرح الخطافات ضمن دليل الإضافات في ووردبريس، حيث يمكنك العثور على معلومات أساسية حول الخطافات، بالإضافة إلى توثيق مفصل حول جميع الإجراءات والفلاتر في ووردبريس وآلية عملها.

مرجع 2: يحتوي هذا الرابط على أداة بحث سهلة الاستخدام تتيح لك البحث عن أي شيء في ووردبريس والعثور على جميع الخطافات والدوال والصفوف البرمجية. كما يعرض لك هذا الرابط في قسم (NEW & UPDATED IN WORDPRESS 5.9) جميع المكونات الجديدة والمحدثة في أحدث إصدار من نظام ووردبريس.

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

مرجع 4: يتضمن هذا المرجع رابطًا للدليل الرسمي لمطوري ووردبريس، والذي يحتوي على رابط يوضح لك جميع خطافات الإجراءات في ووردبريس، ورابط آخر يوضح كافة خطافات الفلاتر في ووردبريس.

الخلاصة

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

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

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

لمزيد من المعلومات عن الخطافات في ووردبريس تواصل معنا من هنا