المرشح (filter) يمرر قيمة عبر دالتك ويأخذ ما تُعيده. قياسا على نسخة ووردبريس 7.1 مُشغَّلة فعلا في 2026-09-24: مرشح يضاعف القيمة عند الأولوية 10، وآخر يضيف 5 عند الأولوية 20، مُطبَّقان على 100، يعيدان 205. الأولوية الأقل تُنفَّذ أولا، والثانية تستقبل ناتج الأولى لا القيمة الأصلية.
والآن الخطأ الذي يصنع أغلب بلاغات الدعم في ووردبريس. دالة مرشح تعدّل القيمة وتنسى أن تُعيدها تجعل apply_filters يعيد NULL. لا القيمة الأصلية ولا رسالة خطأ: عدم، يمرَّر إلى ما كانت النواة ستفعله بالقيمة. كل دالة مرشح تنتهي بكتابة return، بلا استثناء واحد.
الإجراء والمرشح آلية واحدة، بغرضين
- الإجراء (action) لحظة: حدث شيء، افعل ما تشاء، لا يُنتظر منك رد
- المرشح (filter) قيمة في طريقها: غيّرها أو لا، وأعدها في الحالتين
- كلاهما يُنفَّذ بترتيب الأولوية، الأرقام الأصغر أولا، وكلاهما ينفّذ كل دالة مُسجَّلة
- الوسيط الرابع في add_filter هو عدد المعاملات التي تريدها دالتك، وتركه عند الافتراضي 1 بينما دالتك تعلن معاملين خطأ فادح لحظة إطلاق الخطاف
الأخيرة تستحق ذكرا لأن الخطأ يظهر في مكان لا علاقة ظاهرية له: الخطاف يُطلَق من عمق النواة، فالرسالة تسمي ملفا لم تفتحه قط، والسبب رقم واحد ناقص في إضافتك أنت.
كم خطافا مشغولا يحمله المرشح الواحد
هذه النسخة تحمل 711 خطافا مُسجَّلا لحظة بناء الصفحة، والمرشح the_content وحده يحمل أربعة عشر دالة. قراءتها بالترتيب تفسر سلوكا يبدو سحرا لولا ذلك: do_blocks عند الأولوية 9 يعرض ترميز الكتل، وwptexturize وwpautop عند 10 يضبطان الطباعة والفقرات، وdo_shortcode عند 11، وwp_filter_content_tags عند 12 يضيف خصائص الصور.
وهذا سبب أن الأولوية قرار حقيقي لا رقم افتراضي. دالة عند 9 ترى ترميز كتل خاما، والدالة نفسها عند 20 ترى HTML مُعرَّضا كاملا بفقرات وأكواد قصيرة موسّعة فعلا. اختيار الجانب الخطأ من wpautop هو سبب أن عنصرا أُدرج ينتهي داخل وسم فقرة زائد.
إزالة مرشح تحتاج الأولوية والدالة نفسيهما بالضبط، لا الاسم وحده: remove_filter('the_content', 'my_callback', 20) يفشل بصمت إن كانت الدالة مُسجَّلة عند الأولوية 10، لأن ووردبريس يبحث عن التوقيع الكامل الثلاثة. هذا سبب شائع لإضافة يبدو أنها أزالت سلوكا بينما بقي كما كان تماما.
الأداة التي تحوّل القراءة إلى نظر مباشر
Query Monitor هي الأداة، مجانية ومفتوحة المصدر، والإضافة الوحيدة التي تستحق التثبيت على كل موقع تطوير. تسرد الخطافات التي أُطلقت للطلب الحالي مع دوالها، والاستعلامات مع مستدعيها، وتنبيهات PHP، فتحوّل كل هذا من قراءة إلى نظر مباشر. حلّت محل إضافة استدعاءات error_log داخل ملفات النواة نفسها.
WP_DEBUG مع WP_DEBUG_LOG هي الثانية، مجانية مع ووردبريس، ومُعطَّلة افتراضيا في كل نسخة. بتفعيلها يظهر خطأ الإعادة الناقص أعلاه كتنبيه داخل wp-content/debug.log بدل مساحة فارغة في الصفحة. حلّت محل تطوير الموقع بأخطاء مخفية، وهو الوضع الافتراضي وسبب بقاء هذه الأخطاء طويلا دون اكتشاف.
أين يتعثر الناس
إضافة وصفات طعام صغيرة في الرباط أضافت مرشحا على the_content ليدرج جدول تغذية أعلى كل مقال، فعدّلت القيمة ونسيت return واحدا في مسار خطأ نادر، فعادت مقالات قليلة فارغة تماما لكل زائر دون أي رسالة في الواجهة. اكتُشف الخطأ بعد أسبوع، حين قارن أحد القراء المقال بنسخة محفوظة في محرك بحث.
البحث الذي يجد خطافا مفقودا يستغرق دقيقة: grep -rn "apply_filters\|do_action" wp-includes/ متبوعا بما تبحث عنه. أسماء الخطافات وصفية وهي داخل الشيفرة المصدرية نفسها، وهذا البحث أسرع من أي توثيق. مكان تخزين هذه الدوال في القالب موضوعه القوالب، واللغة التي كُتبت بها موضوعها أساسيات PHP.