شرح الخطافات في ووردبريس WordPress Hooks وأهميتها لمطوري القوالب والإضافات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لدينا 3 أنواع من التوابع البرمجية التي تعمل في منظومة الخطافات وهي:

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

مصدر الصورة:https://kinsta.com/blog/wordpress-hooks/

ملاحظة:

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

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

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

يمكننا فقط حمل أشياء معينة على ناقلات محددة متصلة بخطافات معينة، وبالتالي لا يمكن ربط خطافات الإجراءات إلا بدوال الإجراءات Action Functions مثل add_action() و remove_action()  ولا يمكن ربط خطافات المرشحات إلا بدوال  الفلترة Filter Functions  مثل 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 هي عبارة عن سلسلة نصية تمثل اسم الحدث أو الإجراء action الذي سيقع في الموقع ويكون عادة اسم معبر يوضح دلالة هذا الحدث.

[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، هذا البرامتر يحدد أولوية تنفيذ دالة رد النداء المرتبطة بالخطاف وكلما انخفضت قيمة الأولوية فهذا يعني أنه سيتم تشغيل الدالة أبكر.  

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

 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 () في طريقة عملها لكن يتم تمرير الوسطاء لها من خلال مصفوفة array. وهي تعتبر مفيدة عندما تكون الوسطاء الخاصة بك موجودة بالفعل ضمن مصفوفة. أو عندما تحتاج لتمرير الكثير من الوسطاء للدالة.

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

• الدالة has_action:

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

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

has_action( 'action_name', 'function_to_check' );

• الدالة did_action:

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

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

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

• الدالة remove_action

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

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  متطابقين مع الوسيطين المستخدمين عند ربط دالة  رد النداء بهذا الفلتر.

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

// 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
}

تطبيق عملي للتعامل مع لخطافات في ووردبريس برمجيًا

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

حيث يتم عادة تسجيل توابع الخطافات في إضافات ووردبريس في ملفات php  مخصصة ضمن الإضافات، أو ضمن قوالب ووردبريس (في ملف وظائف القالب الأساسي function.php أو ضمن قالب ابن من القالب الأساسي المفعل في موقعك)

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

على سبيل المثال  لتوضيح كيفية عمل الخطافات في ووردبريس سنقوم بإنشاء إضافة جديدة باسم  tryhooks مهمتها تخصيص اللوغو والرابط المعروض في صفحة تسجيل الدخول إلى ووردبريس الموجودة على الرابط http://example.com/wp-login.php باستخدام الخطافات.

فبدلاً من عرض لوغو وورد بريس في الواجهة المبينة أعلاه والذي يؤدي النقر عليه للانتقال لموقع ووردبريس الرسمي سنعرض لوغو موقعنا ووردبريس بالعربية ونجعل النقر فوقه ينقلنا للصفحة الرئيسية للموقع كما يلي:

للقيام بذلك سوف ننشئ بداية مجلد للإضافة المخصصة باسم  tryhooks في الدليل / wp-content / plugins /. وننشئ داخل هذا المجلد ملف باسم tryhooks.php ونقوم بتحريره وإضافة الكود التالي إليه:

<?php
/*
Plugin Name:  Tryhooks
Version    :  1.0
Description:  This is a Test plugin to Demonstrate hooks in WordPress.
Author     :  Ola Saleh
Author URI :  https://www.wpar.net/author/engolasaleh/
Text Domain:  tryhooks
*/

//====1 change WordPress logo image =====
add_action( 'login_enqueue_scripts', 'my_login_logo' );
function my_login_logo() { ?>
    <style type="text/css">
        #login h1 a, .login h1 a {
        background-image: url(<?php echo content_url(); ?>/plugins/tryhooks/images/wparlogo.png);
		height:300px;
		width:300px;
        padding-bottom: 5px;
		background-size: 300px 300px;
		background-repeat: no-repeat;
        }
    </style>
<?php }

//====2 change login logo URL=====
add_filter( 'login_headerurl', 'my_login_logo_url' );

function my_login_logo_url() {
    return home_url();
}

//====3 change login logo URL title=====
add_filter( 'login_headertext', 'my_login_logo_url_title' );
function my_login_logo_url_title() {
    return 'الدليل العربي لتعلم ووردبريس';
}

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

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

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

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

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

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

الخطوة التالية هي تعريف كل دالة من دوال رد النداء وكتابة الكود المخصص الذي نريد تنفيذه بداخلها وتذكر ستنفذ هذه الداول آليًا عند حدوث كل خطاف من الخطافات التي قمنا بربطها معه

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

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

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

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

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

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

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

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

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

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

الخلاصة

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

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

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