برمجة إضافات ووردبريس: الخُطّافات (Hooks)

كما ذكرنا في الدرس السابق (مدخل إلى برمجة إضافات ووردبريس) من هذه السلسلة فإن الخطّافات تعد من أهم الخصائص التي يوفرها ووردبريس والتي جعلته مرنًا flexible وقابل للتمدد extensible بصورة قل أن تجد لها نظيرًا في برمجيات الويب حيث يعتمد على توفير نقاط ربط تمكن المطورين من تنفيذ الدّوال التي يريدونها أثناء دورة حياة ووردبريس، وذلك باعتماده على معمارية Event Driven.
يوفر ووردبريس للمطورين الاستفادة من هذه الميزة من خلال ما يعرف بالواجهة البرمجية للإضافة Plugin API والتي نحن بصدد الإطلاع على أهم الدّوال التي توفرها في جانبي الإجراءات Actions والمُرشّحات Filters وبعض الأمثلة التوضيحية التي ترسخ فهم هذه الدّوال والمفاهيم المتعلقة بها.

الإجراءات في ووردبريس

الدالة add_action

ذكرنا سابقًا أنه يمكنك إضافة إجراء لحدث معين من خلال الدالة add_action لكننا لم نذكر الصّيغة العامة للدالة وتفاصيل المعاملات التي تقبلها، وهذه هي الصّيغة العامة للدّالة:

add_action( $hook, $function_to_add, $priority, $accepted_args );

حيث:

$hook : هو الحدث الذي تريد أن تربط به الدالة الخاصة بك، أي الحدث التي تريد أن تنفذ دالتك عند حدوثه. ويمكنك الإطلاع على ا لأحداث التي يوفرها ووردبريس من هنا.
$function_to_add:اسم الدالة (الإجراء) التي تريد إضافتها للحدث أعلاه. أي التي ستنفذ عند حصول الحدث $hook .
$priority (اختياري): هذه هي أولوية تنفيذ الدالة عند هذا الحدث، بمعنى أنه إذا كان هنالك أكثر من دالة تم إضافتها باستخدام الدالة add_action إلى نفس الحدث فإن قيمة هذا المعامل ستحدد أي الدّوال ستنفذ أولا وأيها ثانيا وهكذا. قيمة هذا المعامل يجب أن تكون من النوع int، وقيمته الافتراضية 10 والحدث ذو القيمة الأقل سينفذ أولا، بمعنى أن الدالة التي لديها قيمة 5 ستنفذ قبل الدالة التي لديها 20 وهكذا.
$accepted_args (اختياري): عدد المعاملات التي تقبلها الدالة المطلوب تنفيذها $function_to_add، فمثلا الإجراء publish_post يقوم بتمرير معرف المقال الذي تم نشره للدالة المطلوب تنفيذها. وعادة يتم تحديد هذه من قبل الخطاف نفسه.

استخدام add_action مع الفئات Classes

أحيانًا قد تود استخدام الدالة add_action لإضافة دالة تابعة لفئة أو لكائن Object معين حينئذ ينبغي عليك استخدام add_action كما في المثال التالي:

class MyPluginClass {
   public function __construct() {
      add_action( 'save_post', array( $this, 'myplugin_save_posts' ) );
   }
   public function myplugin_save_posts() {
      // do stuff here...
   }
}
$mypluginclass = new MyPluginClass();

وتلاحظ أننا استخدمنا اسم الحدث save_post وفي المعامل الثاني أشرنا إلى الدالة من خلال المصفوفة

array( $this, 'myplugin_save_posts' )

حيث تشير $this إلى الكائن الحالي وmyplugin_save_posts تشير إلى اسم الدالة التي نود إضافتها للحدث.

الدالة remove_action

تعُتبر دالة remove_action الدالة العكسية للدالة add_action حيث تقوم بحذف الدالة التي تريدها من الحدث الذي تريده وتأخذ الصّيغة العامة التالية:

remove_action( $tag, $function_to_remove, $priority );

حيث:

$tag : اسم الحدث الذي تم إضافة الدالة إليه
$function_to_remove : الدالة التي تود حذفها من الحدث $tag
$priority (اختياري): أولوية الدالة التي تريد حذفها والتي تم تعريفها مسبقا عند إضافة الدالة إلى الحدث عن طريق add_action

الدالة has_action

تستخدم دالة has_action لاختبار إذا كانت دالة معينة قد أضيفت إلى حدث معين، والصّيغة العامة لهذه الدالة هي:

has_action( $tag, $function_to_check )

حيث

$tag : الحدث الذي تود معرفة إذا ما كانت الدالة قد أضيفت إليه.
$function_to_check : الدالة التي تود معرفة إذا ما كانت أضيفت إلى الحدث $tag أما لا.
القيمة المرجعة من الدالة: ترجع هذه الدالة قيمة false إذا كانت الدالة $function_to_check غير مضافة للحدث $tag وترجع أولوية تنفيذها priority إذا كانت مضافة للحدث $tag.

الدالة do_action

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

 do_action( $tag, $arg );

حيث:

$tag : اسم الإجراء الذي تود تنفيذه. وكما أسلفنا فإن هذه الدالة عند مناداتها ستنفذ كل الدّوال التي تم إضافتها لهذا الحدث $tag.
$arg (اختياري): المعامل الذي يتم تمريره للدوال المرتبطة بالحدث $tag

هذه الدالة في الأساس يستخدمها ووردبريس ليحدد مكان تنفيذ ا لأحداث التي يوفرها لكن يمكنك أيضا استخدامها لإنشاء أحداث خاصة بك في حالة أردت مثلا أن تتيح للمطورين نقاط معينة داخل إضافتك (أو قالبك) لينفذوا فيها دوالهم الخاصة، وبهذه الطريقة يمكن إنشاء إضافات قابلة لتشتغل عليها إضافات أخرى أو ما يمكن أن نطلق عليه اسم Extensions وهنالك عدة أمثلة لإضافات ناجحة توفر هذه الميزة نذكر منها على سبيل المثال إضافة Bbpress المشهورة وكذلك إضافة Woocommernce حيث أن هاتين الإضافتين تعمل فوقهما عدة إضافات أخرى تزيد من مميزاتهما، وتقريبا معظم إضافات ووردبريس توفر مجموعة من الخطافات hooks للمطورين، لذلك في حالة فكرت في إنشاء إضافة لنشرها في مجتمع ووردبريس من الجيد أن تجعل نظرتك مستقبلية وتوفر بعض الخطافات للمطورين.
يحسن التنبيه إلى أن الدالة do_action يمكن أن تستدعى بأكثر من معامل بالصّيغة التالية

do_action( $tag, $arg_a, $arg_b, $etc );

وكما أسلفنا في تعريف معاملات الدالة add_action تستطيع تحديد المعاملات التي تقبلها الدالة المضافة إلى add_action، ولتحديد القيمة هناك عليك أن ترى عدد المعاملات الموجودة هنا في do_action.

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

التعامل مع ملفات جافاسكربت

في ووردبريس إذا أردت أن تضيف ملف جافاسكربت للموقع فإن أفضل طريقة -غالبًا- هي استخدام الحدث wp_enqueue_scripts والذي تستطيع من خلاله إضافة ملفاتك إلى بقية ملفات جافاسكربت (أو CSS) وتترك لووردبريس مهمة ربطها في ترويسة الموقع وهذا ما تفعله الشيفرات التالية

function my_scripts_method() {
   wp_enqueue_script(
   'myscript', // اسم ملف جافاسكربت
   plugins_url( '/js/newscript.js' , __FILE__ ) // مكان ملف الجافاسكربت
);
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );

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

إضافة قائمة جانبية Sidebar جديدة

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

function create_my_widget() {
 register_sidebar(array(
 'name' => __( 'My Sidebar'), 			// اسم القائمة الجانبية  
 'id' => 'my_sidebar',					// معرف القائمة الجانبية
 ));
}
add_action( 'widgets_init', 'create_my_widget' );

لاحظ أننا في السطر الأخير أضفنا الدالة create_my_widget إلى الحدث widget_init والذي يستخدمه ووردبريس لتعريف جميع القوائم الجانبية، وداخل الدالة قمتا باستخدام دالة أخرى وهي الدالة register_sidebar والتي تأخذ اسم القائمة الجانبية ومعرفها الفريد وتتولى مهمة تسجيلها.

إنشاء خطاف إجراء action hook خاص بك

لعمل ذلك كل ما عليك هو إضافة الدالة do_action إلى المكان الذي تود أن تنفذ فيه الدّوال التي تربط بهذا الخطاف وبالطبع ستمرر للدالة do_action الاسم الذي تود أن تسمي به الخطاف، بالصّيغة التالية

do_action('my_action_hook');

وبالطبع يمكنك إضافة بقية المعاملات التي ذكرناها في تعريف الدالة do_action كلما اقتضت الحاجة.

المرشحات في ووردبريس

بنفس الطريقة التي اتبعناها في الأحداث أعلاه سنتعرف على أهم الدّوال الخاصة بالمرشحات التي يوفرها ووردبريس

الدالة add_filter

تستخدم دالة add_filter لإضافة مرشح جديد لأحد المتغيرات وتأخذ الصّيغة العامة:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

لاحظ أن الدالة شبيهة جدا بالدالة add_action وكذلك المعاملات هي نفسها تقريبا، لكن لا باس من إعادة تعريفها:

$tag: اسم خطاف المرشح filter hook الذي تود أن تضيف له الدالة $function_to_add لكي تعدل على قيمة المتغير الذي يمثله الخطاف.
$function_to_add: الدالة التي ستتولى عملية التعديل على المتغير الذي يشير اليه الخطاف $tag. وهذه الدالة تقوم بإرجاع القيمة الجديدة للمتغير الذي تستقبله.
$priority : أولوية التنفيذ للدوال المضافة لنفس الخطاف، حيث تحدد قيمة هذا المتغير ترتيب تنفيذ الدّوال المرتبطة بهذا المرشح. ويأخذ المتغير $priority قيمة من النوع int.
الدّوال التي لها $priority أقل تنفذ أولا، وإذا كان هنالك أكثر من دالة لها نفس قيمة المتغير $priority حينئذ يتم تنفيذها على حسب ترتيب تعريفها.
$accepted_args: عدد المعاملات arguments التي تقبلها الدالة $function_to_add. حيث يمكن تعريف أكثر من معامل للخطاف عند تنفيذه من خلال apply_filters كما سنرى في الفقرات القادمة. وعدد المعاملات عادة يتم تحديد من خلال الخطاف نفسه.

الدالة remove_filter

كما يظهر من اسمها فإن remove_filter الدالة العكسية لـadd_filter وتأخذ الصّيغة التالية

remove_filter( $tag, $function_to_remove, $priority );

حيث:

$tag: اسم خطاف المرشح الذي تود إزالة الدالة عنه.
$function_to_remove: اسم الدالة التي تود إزالتها.
$priority (اختياري): أولوية الدالة التي تود إزالتها كما تم تعريفها باستخدام add_filter

الدالة has_filter

تقوم الدّالة has_filter باختبار ما إذا كان هنالك دالة تم إضافتها لخطاف معين، وتأخذ الصّيغة التالية

has_filter( $tag, $function_to_check );

حيث:

$tag: اسم خطاف المرشح.
$function_to_check: اسم الدالة التي تريد التأكد من وجودها

الدالة apply_filters

تقوم دالة apply_filters بتنفيذ الدّوال المرتبطة بالخطاف الذي يمرر لها كمعامل وتأخذ الصّيغة العامة

apply_filters( $tag, $value, $var ... );

حيث:

$tag : اسم الخطاف المراد تنفيذ الدّوال التي تم إضافتها له من خلال add_filter
$value : القيمة الأصلية للمتغير والتي يتم تغيرها من خلال الدّوال المربوطة بالخطاف، أي القيمة التي ترشح من خلال الدّوال.
$var (اختياري): متغير إضافي أو أكثر يتم تمريرها إلى الدّوال المرتبطة بالخطاف $tag وكنا قد ذكرنا أنه بالإمكان تحديد عدد المتغيرات التي تستقبلها الدالة المربوطة بالخطاف من خلال المعامل $accepted_args للدالة add_filter حيث تقوم بعد المعاملات هنا وتحديد عددها عند إضافة أي دالة لهذا الخطاف.

أمثلة للمرشحات في ووردبريس

تعديل عدد كلمات المقتطف

في هذا المثال سنستخدم الخطاف excerpt_length الذي يوفره ووردبريس للتعديل على قيمة طول نص المقتطف

function excerpt_length_example( $words ) {
 return 15;
}
add_filter( 'excerpt_length', 'excerpt_length_example' );

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

إنشاء خطاف مرشح filter hook لأحد متغيراتك

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

$text = apply_filters("my_text", $text);

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

أسماء الخطافات المتغيرة Variable Hook Names

الخطافات التي اطلعنا عليها أعلاه ليست كل ما يوفره ووردبريس بل هنالك المزيد من المرونة المتاحة من خلال أسماء الخطافات المتغيرة فمثلا لنلقى نظرة على الخطاف publish_post وهو عبارة عن خطاف حدث action hook يوفره ووردبريس ويتم تنفيذ الدّوال المرتبطة به كلما تم نشر publish مقال post وهذا في الحقيقة خطاف جميل جدا يمكنك من تنفيذ أي دالة تريدها عندما يتم نشر أي مقال لكن ماذا إن أردت تنفيذ دالة معينة عند نشر نوع مقالات مخصص ولتكن مثلا منتجات، أي نريد تنفيذ الدالة my_function عندما يتم نشر publish منتج product، هذا الأمر انتبه له المطورون ولذلك قاموا بإضافة هذا الخطاف ذو الاسم العام

{$new_status}_{$post->post_type}

وكما ترى فإنه يوفر مرونة عالية جدا حيث يمكنك اختيار الحالة التي تريد التنفيذ عنها وأصبح الأمر ليس مقتصرا على النشر فقط publish بل يمكنك مثل تنفيذ شئ معين عند حذف delete مقال أو عموما تغير حالة المقال إلى أي حالة {$new_status}. كما أن الأمر لم يعد مقتصرا على المقالات فقط بل يمكنك تحديد نوع المقال {$post->post_type} وهكذا اصبح الخطاف publish_post حالة خاصة من خطاف أعم له الاسم العام {$new_status}_{$post->post_type}.
هذا مثال واحد فقط لأسماء الخطافات المتغيرة وهنالك خطافات متغيرة غيره يوفرها ووردبريس لإتاحة المزيد من المرونة للمطورين.

خاتمة

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