الوسم: WordPress Hooks

# إنشاء إضافة ووردبريس بسيطة للمبتدئين

**الرابط الدائم المقترح (Slug):** `build-wordpress-plugin`

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

**التصنيف:** الإضافات

**الوسوم:** تطوير إضافات ووردبريس، PHP، WordPress Hooks، برمجة ووردبريس

**الكلمة المفتاحية الرئيسية:** تطوير إضافات ووردبريس

**كلمات مفتاحية ثانوية:** إنشاء إضافة ووردبريس، WordPress Plugin development، PHP ووردبريس

## مقدمة

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

الإضافة (Plugin) هي حزمة برمجية مستقلة توسع ووردبريس دون الحاجة إلى تعديل الملفات الأساسية للنظام. وهذا الفصل بين كودك وملفات النواة يساعدك على تحديث ووردبريس دون فقد التعديلات التي كتبتها.

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

## ما الذي تحتاجه قبل البدء؟

ستحتاج إلى:

– موقع ووردبريس تجريبي أو بيئة Staging.
– محرر نصوص أو محرر أكواد.
– معرفة أساسية بملفات PHP.
– وصول إلى مجلد `wp-content/plugins` إذا كنت تعمل من الخادم.

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

## بنية الإضافة

أنشئ مجلدًا باسم:

“`text
simple-content-note
“`

ثم أنشئ داخله ملفًا رئيسيًا باسم:

“`text
simple-content-note.php
“`

ستبدو البنية هكذا:

“`text
wp-content/
└── plugins/
└── simple-content-note/
└── simple-content-note.php
“`

يمكن أن تكون الإضافات الكبيرة مقسمة إلى ملفات ومجلدات أكثر، لكن المثال الحالي لا يحتاج إلى ذلك.

## أضف رأس الإضافة

ابدأ الملف بالكود التالي:

“`php
<?php
/**
* Plugin Name: Simple Content Note
* Description: Adds a small note below published post content.
* Version: 1.0.0
* Author: Site Admin
*/
“`

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

## ما هو Hook؟

الـHook هو نقطة يوفرها ووردبريس للسماح بإضافة كودك في مرحلة محددة من تنفيذ النظام.

هناك نوعان مشهوران:

– **Action:** لتنفيذ شيء ما عند حدوث حدث.
– **Filter:** لتعديل قيمة قبل أن تعاد أو تعرض.

سنستخدم Filter لأنه يسمح لنا بتعديل محتوى المقال قبل عرضه.

## بناء أول دالة

أضف الدالة التالية:

“`php
function simple_content_note( $content ) {
if ( is_single() && is_main_query() && in_the_loop() ) {
$content .= '

‘;
}

return $content;
}
“`

ثم اربطها بالفلتر:

“`php
add_filter( ‘the_content’, ‘simple_content_note’ );
“`

الآن سيستقبل الفلتر محتوى المقال، وتتحقق الدالة من أن الطلب يعرض مقالة مفردة ضمن الحلقة الرئيسية، ثم تضيف العنصر في النهاية.

## الملف كاملًا

يمكنك وضع الكود التالي كما هو داخل الملف:

“`php
<?php
/**
* Plugin Name: Simple Content Note
* Description: Adds a small note below published post content.
* Version: 1.0.0
* Author: Site Admin
*/

function simple_content_note( $content ) {
if ( is_single() && is_main_query() && in_the_loop() ) {
$content .= '

‘;
}

return $content;
}

add_filter( ‘the_content’, ‘simple_content_note’ );
“`

هذا المثال صغير عمدًا. الهدف أن تفهم مكان كودك وكيف يمر عبر ووردبريس، لا أن تبني نظامًا كبيرًا دفعة واحدة.

## كيف تفعل الإضافة؟

بعد رفع المجلد إلى `wp-content/plugins`، افتح لوحة التحكم ثم **إضافات**. ستجد الإضافة باسمها، ويمكنك الضغط على **تفعيل**.

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

## تحسين المثال باستخدام escaping

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

مثلًا عند طباعة نص من متغير، يمكن استخدام `esc_html()` للنصوص HTML أو `esc_attr()` للسمات بحسب مكان الاستخدام.

مثال:

“`php
$message = ‘رسالة آمنة’;
echo ‘

‘ . esc_html( $message ) . ‘

‘;
“`

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

## أضف CSS دون كتابة style داخل المحتوى

عندما يصبح المشروع حقيقيًا، من الأفضل فصل التنسيق عن HTML. أنشئ ملفًا باسم:

“`text
style.css
“`

ثم أضف:

“`css
.simple-content-note {
padding: 12px;
margin-top: 20px;
border: 1px solid #ddd;
border-radius: 4px;
}
“`

بعد ذلك يمكنك تحميل الملف من خلال `wp_enqueue_style()` بدل إدراج CSS مباشرة في PHP.

“`php
function simple_content_note_assets() {
wp_enqueue_style(
‘simple-content-note’,
plugin_dir_url( __FILE__ ) . ‘style.css’,
array(),
‘1.0.0’
);
}

add_action( ‘wp_enqueue_scripts’, ‘simple_content_note_assets’ );
“`

الهدف من ذلك أن يبقى الكود منظمًا وقابلًا للصيانة.

## استخدم أسماء Functions فريدة

لا تستخدم اسمًا عامًا مثل:

“`php
function add_note() {}
“`

قد يكون الاسم مستخدمًا من قالب أو إضافة أخرى. في المثال استخدمنا بادئة `simple_content_note` حتى تقل احتمالية التصادم.

في المشاريع الكبيرة يستخدم المطورون Prefix خاصًا بالمشروع أو Namespace عند بناء كود حديث.

## لا تعدل ملفات نواة ووردبريس

إذا أردت تغيير سلوك ووردبريس، ابحث أولًا عن Hook مناسب. تعديل ملفات النواة يجعل التحديثات أصعب ويمكن أن يحذف تغييراتك.

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

## كيف تختبر الإضافة؟

ابدأ باختبارات صغيرة:

1. فعّل الإضافة على Staging.
2. افتح مقالة منشورة.
3. تأكد من ظهور الرسالة مرة واحدة.
4. افتح الصفحة الرئيسية وتأكد من عدم تكرار الإخراج في مكان غير مقصود.
5. افتح صفحة تصنيف أو أرشيف واختبر السلوك المتوقع.
6. عطّل الإضافة وتأكد من اختفاء التغيير.

إذا كان موقعك يحتوي على Cache، امسح الكاش أثناء الاختبار عند الحاجة حتى لا ترى نسخة قديمة.

## مثال آخر: إضافة نص باستخدام Action

لفهم الفرق بين Filter وAction، يمكن إضافة رسالة إلى تذييل الصفحة باستخدام Hook مناسب، لكن لا يُنصح بإرسال HTML من جميع الإجراءات دون فهم مكان تنفيذها.

المهم أن تتذكر القاعدة الأساسية: Filter يعيد قيمة معدلة، بينما Action ينفذ كودًا عند نقطة معينة.

## تنظيم الإضافة عند نموها

عندما يتوسع المشروع، انتقل من ملف واحد إلى بنية أوضح، مثل:

“`text
simple-content-note/
├── simple-content-note.php
├── includes/
│ └── class-plugin.php
├── assets/
│ ├── css/
│ └── js/
└── readme.txt
“`

ليس الهدف إنشاء مجلدات كثيرة بلا حاجة. استخدم بنية تناسب حجم المشروع.

## أخطاء شائعة عند المبتدئين

### نسيان `return $content`

إذا استخدمت `the_content` Filter ولم تُرجع المحتوى، فقد تختفي المقالة من الصفحة.

### تنفيذ الكود في كل طلب

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

### عدم اختبار الكود على Staging

خطأ Syntax أو Fatal Error يمكن أن يؤثر في الموقع. البيئة التجريبية أفضل مكان للتعلم.

### استخدام أسماء دوال عامة

استخدم Prefix أو Namespace لتقليل احتمالات التصادم.

## متى تحتاج إلى Plugin ومتى يكفي Snippet؟

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

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

## أسئلة شائعة

### هل يمكن إنشاء إضافة ووردبريس بدون خبرة كبيرة؟

نعم، الإضافات البسيطة يمكن بناؤها بتعلم أساسيات PHP وHooks وبنية ملفات ووردبريس، ثم التدرج إلى مشاريع أكبر.

### هل يجب استخدام Class في كل إضافة؟

ليس في الإضافة الصغيرة. يمكن أن يبدأ المشروع بدوال منظمة، ثم تنتقل إلى Classes أو Namespaces عندما يكبر حجم الكود.

### أين أضع ملفات الإضافة؟

عادة داخل `wp-content/plugins/اسم-الإضافة`، مع ملف PHP رئيسي يحتوي على رأس الإضافة.

### هل تعديل ملفات ووردبريس الأساسية آمن؟

ليس خيارًا مناسبًا للتخصيصات المعتادة. استخدم Hooks والإضافات والطبقات التي يوفرها النظام حتى تبقى التحديثات ممكنة.

## الخاتمة

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

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

## اقتراحات الربط الداخلي

– **ما هي إضافات ووردبريس وكيف تختارها بأمان؟** — نص الرابط: «اختيار إضافات ووردبريس بأمان».
– **كيف تعرف سبب تعارض إضافات ووردبريس؟** — نص الرابط: «تشخيص تعارض الإضافات».
– **كيف تستخدم WP-CLI لإدارة ووردبريس؟** — نص الرابط: «إدارة ووردبريس عبر WP-CLI».

## Alt Text مقترح للصور

– بنية ملفات إضافة ووردبريس بسيطة داخل مجلد plugins.
– ملف PHP يحتوي على رأس إضافة ووردبريس.
– مثال على استخدام the_content Filter في ووردبريس.
– شاشة تفعيل إضافة مخصصة من لوحة تحكم ووردبريس.
– مثال على ملف CSS داخل إضافة ووردبريس.