دليل البدء في تطوير إضافات ووردبريس: بناء أول إضافة خاصة بك من الصفر

إعداد بيئة تطوير المكوّنات الإضافيّة لـ WordPress.

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

أولاً، تحتاج إلى بيئة خادم محلية قادرة على تشغيل ووردبريس. يُنصح باستخدام حزم البيئات المتكاملة مثل Laragon أو XAMPP أو Local by Flywheel، حيث تقوم هذه الأدوات بتثبيت Apache/Nginx وPHP وMySQL بنقرة واحدة، مما يوفر عليك عناء عمليات الإعداد المعقدة. تأكد من أن إصدار PHP الخاص بك متوافق مع أحدث إصدارات ووردبريس؛ عادةً ما يُنصح باستخدام PHP 7.4 أو إصدارات أحدث. بالإضافة إلى ذلك، في واجهة ووردبريس الخلفية، ضمن قسم “الأدوات” → “صحة الموقع” (Tools → Site Health)، تأكد من عدم وجود مشاكل رئيسية قد تؤثر على تطوير الإضافات (البرامج الإضافية).

ثانيًا، اختر محرر كود قوي. Visual Studio Code هو خيار شائع جدًا في الوقت الحالي؛ فهو خفيف الوزن ومجاني، ويحتوي على العديد من الإضافات المفيدة مثل PHP Intelephense (للحصول على تلميحات ذكية أثناء كتابة الكود) و WordPress Snippet (لمقتطفات الكود الجاهزة للاستخدام). خيار آخر كلاسيكي هو PhpStorm، الذي يوفر دعمًا أكثر تخصصًا لتطوير مواقع ووردبريس، لكنه برنامج مدفوع.

القراءة الموصى بها من الصفر إلى الواحد: دليل شامل لتطوير إضافات ووردبريس وأفضل الممارسات。

أخيرًا، تفعيل وضع التصحيح (Debug Mode) هو خطوة ضرورية لا غنى عنها أثناء عملية التطوير. وذلك عن طريق تعديل الملفات الموجودة في المجلد الرئيسي لـ WordPress.wp-config.phpيمكنك تفعيل تقارير الأخطاء المفصلة للملفات، وهو أمر بالغ الأهمية لاكتشاف وإصلاح المشكلات الموجودة في الكود. قم بالبحث عن التعريفات الموجودة داخل الملف.WP_DEBUGفي المكان الذي توجد فيه الثوابت (constants)، أضف الكود التالي:

خادم ووردبريس من شركة UltaHost

ضمان استرداد المال خلال 30 يومًا، عرض نطاق ترددي وقواعد بيانات غير محدودين، حماية مجانية ضد هجمات DDoS، خصم 50% عند الشراء لمدة 3 سنوات (السعة المتاحة: 501–4 تيرابايت).

صفحة الوصول

// 启用 WordPress 调试模式
define( 'WP_DEBUG', true );
// 将错误记录到 /wp-content/debug.log 文件
define( 'WP_DEBUG_LOG', true );
// 在页面上显示错误（开发环境推荐，生产环境必须关闭）
define( 'WP_DEBUG_DISPLAY', true );

قم بإنشاء ملف الإضافة (plugin) الخاص بك الأول.

قد يكون إضافة ووردبريس بسيطة للغاية، حيث تتكون فقط من ملف واحد. يجب أن تُخزن جميع الإضافات في المكان المحدد من قبل ووردبريس لكي تعمل بشكل صحيح./wp-content/plugins/داخل المجلد، يمكن لكل إضافة (plugin) أن يكون لها مجلد فرعي خاص بها، وهذا يساعد على تنظيم هيكل الكود بشكل أكثر تعقيدًا.

تعليقات رأس الإضافة (Plugin Header Comments)

يجب أن يبدأ كل ملف رئيسي للإضافة (plugin) بتعليقات رأسية (header comments) موحدة للغة PHP، وهذا هو الطريقة التي يتعرف بها WordPress على معلومات الإضافة. قم بإنشاء ملف جديد وأطلق عليه…my-first-plugin.phpووضعه داخل…/wp-content/plugins/my-first-plugin/موجود في المجلد. محتوى الملف كالتالي:

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个用于学习WordPress插件开发的入门示例插件。
 * Version:           1.0.0
 * Author:            你的名字
 * Author URI:        https://example.com
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 * Domain Path:       /languages
 */

توفر هذه الملاحظة جميع المعلومات الوصفية (الميتا) التي يتم عرضها للإضافة (البرنامج الإضافي) على صفحة “الإضافات” في واجهة ووردبريس الخلفية.Text DomainوDomain Pathيُستخدم للاستعداد لترجمة الواجهات والمحتويات الخاصة بالإضافات (البرامج الإضافية) إلى لغات أخرى (عملية التدويل أو i18n – Internationalization).

تنفيذ وظيفة بسيطة

الآن، دعونا نضيف ميزة بسيطة لهذا الإضافة: إضافة سطر نصي مخصص تلقائيًا في نهاية محتوى المقال. سنستخدم إمكانيات ووردبريس (WordPress) لتحقيق ذلك.the_contentمخالب المرشحات (Filter Hooks): التي قمت بإنشائها للتو…my-first-plugin.phpأضف الدالة التالية أسفل تعليقات رأس الملف:

القراءة الموصى بها إتقان تطوير إضافات ووردبريس: بناء وظائف مخصصة من الصفر。

// 在文章内容末尾添加自定义文本
function my_first_plugin_add_footer_text( $content ) {
    // 确保只在主循环的单篇文章页面执行
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $footer_text = '<p><em>شكرًا لقراءتكم! تم تقديم هذا المقال من قبل “أول إضافة لي” (My First Plugin).</em></p>';
        $content .= $footer_text;
    }
    return $content;
}
add_filter( 'the_content', 'my_first_plugin_add_footer_text' );

بعد حفظ الملف، قم بتسجيل الدخول إلى واجهة ووردبريس الخلفية (الواجهة الإدارية) الخاصة بك، ثم اذهب إلى صفحة “الإضافات” (Plugins). يجب أن ترى إضافة بعنوان “أول إضافة لي” (My First Plugin). قم بتفعيلها، ثم اطلع على مقالة في المدونة؛ ستلاحظ أن النص الذي حددناه قد تم إضافته بنجاح في نهاية محتوى المقالة.

استخدام واجهة برمجة التطبيقات (API) الأساسية لووردبريس (WordPress Core API)

أثناء عملية التطوير المتقدم، ستتعامل بشكل متكرر مع مجموعة متنوعة من واجهات برمجة التطبيقات (APIs) التي يوفرها ووردبريس (WordPress). أهم هذه الواجهات هو نظام “الخطافات” (Hooks)، والذي يشمل “الإجراءات” (Actions) و“المرشحات” (Filters).

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

تسمح “خطافات الإجراءات” (Action Hooks) بتنفيذ كود مخصص في أوقات محددة. على سبيل المثال، عند نشر مقال، قد ترغب في إرسال بريد إلكتروني لإبلاغ المستخدمين. في هذه الحالة، يمكنك استخدام هذه الميزة.publish_postالأمثلة التالية توضح كيفية إنشاء وظيفة تسجيل المعلومات في سجل الأخطاء عند نشر المقالات:

استضافة.كوم استضافة مشتركة

أداء عالٍ مع وحدات المعالجة المركزية AMD EPYC، ووحدات تخزين NVMe SSD وLiteSpeed، ودعم داخلي متخصص على مدار الساعة طوال أيام الأسبوع، وتدابير أمنية متقدمة بما في ذلك SSL، وقوة الغاشمة، والحماية من البرامج الضارة والحماية من DDoS، وتوفير ما يصل إلى 731 تيرابايت 4 تيرابايت

صفحة الوصول

// 定义文章发布时执行的动作函数
function my_first_plugin_log_post_published( $post_id, $post ) {
    // 避免无限循环和非文章类型
    if ( wp_is_post_revision( $post_id ) || $post->post_type != ‘post’ ) {
        return;
    }
    // 记录日志
    error_log( “文章 ID {$post_id} 已发布，标题为：{$post->post_title}” );
}
// 将函数挂载到 publish_post 动作钩子上
add_action( ‘publish_post’， ‘my_first_plugin_log_post_published’， 10, 2 );

دالةadd_actionالمعلمة الثالثة هي الأولوية (القيمة الافتراضية هي 10)، كلما كان الرقم أصغر كانت الأولوية أعلى؛ أما المعلمة الرابعة فهي عدد المعاملات (الوسائط) التي تقبلها الدالة.

فهم خطافات التصفية

تُستخدم “خطافات المرشحات” (filter hooks) لتعديل البيانات. في الفصل الذي يحمل عنوان “إنشاء ملف الإضافة الخاصة بك الأول”， كنا قد استخدمناها بالفعل.the_contentإنه مجرد خطاف (hook) لمرشح (filter)؛ يستقبل المحتوى الأصلي ويسمح لك بتعديله قبل إرجاعه. مثال آخر شائع على استخدامه هو تعديل طول ملخص المقال.

// 修改摘要的默认字数
function my_first_plugin_custom_excerpt_length( $length ) {
    return 30; // 将摘要字数改为30字
}
add_filter( ‘excerpt_length’， ‘my_first_plugin_custom_excerpt_length’ );

إضافة قائمة الدخول

للتفاعل مع المستخدمين، عادةً ما نحتاج إلى إضافة صفحة قائمة إلى شريط الإدارة في الواجهة الخلفية لـ WordPress. ويمكن تحقيق ذلك عن طريق…add_menu_pageتنفيذ الدالة: الكود أعلاه يضيف صفحة إعدادات رئيسية للإضافة.

القراءة الموصى بها دليل شامل لتطوير إضافات ووردبريس: كيفية بناء وظائف إضافية عالية الجودة لووردبريس من الصفر。

// 创建插件管理菜单
function my_first_plugin_add_admin_menu() {
    add_menu_page(
        ‘我的第一个插件设置’， // 页面标题
        ‘我的插件’，           // 菜单标题
        ‘manage_options’，     // 所需权限
        ‘my-first-plugin’，    // 菜单slug
        ‘my_first_plugin_settings_page’， // 回调函数，用于输出页面内容
        ‘dashicons-admin-plugins’， // 图标（可选）
        100                    // 菜单位置（可选）
    );
}
add_action( ‘admin_menu’， ‘my_first_plugin_add_admin_menu’ );

// 设置页面的回调函数
function my_first_plugin_settings_page() {
    ?>
    <div class="“wrap”">
        <h1>إعدادات الإضافة الأولى الخاصة بي</h1>
        <p>هذه هي صفحة إعدادات الإضافة. في المستقبل، ستتمكن من إضافة النماذج والخيارات من خلال هذه الصفحة.</p>
    </div>
    أنا لا أعرف ماذا أقول.

أمان الإضافات وأفضل الممارسات

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

التحقق من صحة البيانات وتهيئتها للاستخدام (Data Validation and Escaping)

لا تثق أبدًا بالبيانات المدخلة من قبل المستخدمين أو البيانات الموجودة في قاعدة البيانات. يجب تنفيذ عمليات تهريب (escaping) لهذه البيانات قبل عرضها في المتصفح، ويجب أيضًا التحقق من صحتها وتنقيتها قبل حفظها في قاعدة البيانات. يوفر ووردبريس العديد

الاستضافة المشتركة InterServer

استضافة مشتركة $2.50 دولار أمريكي في الشهر، الشهر الأول $0.1 دولار أمريكي الرمز الترويجي tryinterserver، 461 نص برمجي للتطبيقات السحابية، تثبيت بنقرة واحدة.

صفحة الوصول

• إخراج الكود المهرب: استخدم Escape output: Use <esc_html()、esc_attr()、esc_url()وwp_kses_post()وظائف مثل هذه تقوم بتهجئة البيانات وفقًا للسياق المحيط.
• تحقق من المدخلات: استخدمsanitize_text_field()、sanitize_email()、intval()تقوم الدوال مثل هذه بتنظيف بيانات النماذج التي يقوم المستخدمون بتقديمها.

على سبيل المثال، عند إعداد صفحة لمعالجة بيانات النموذج:

$user_input = $_POST[‘some_field’] ?? ‘’; // 使用空合并运算符提供默认值
$clean_input = sanitize_text_field( $user_input ); // 清理数据
update_option( ‘my_plugin_option’， $clean_input ); // 安全存储

استخدام طرق غير مرتبطة ببروتوكول CE (Common Edge) وعمليات التحقق من الصلاحيات

عند معالجة طلبات النماذج (وخاصة تلك القادمة من ملفات admin-ajax.php أو admin-post.php)، يجب استخدام…wp_verify_nonce()يتم استخدام هذا للتحقق من شرعية الطلبات ومنع هجمات تزوير الطلبات بين المواقع (Cross-Site Request Forgery – CSRF).current_user_can()تحقق مما إذا كان لدى المستخدم الحالي الصلاحيات اللازمة لتنفيذ العملية المطلوبة.

function my_first_plugin_handle_form_submit() {
    // 1. 检查nonce
    if ( ! isset( $_POST[‘my_nonce_field’] ) || ! wp_verify_nonce( $_POST[‘my_nonce_field’]， ‘my_action’ ) ) {
        wp_die( ‘安全校验失败！’ );
    }
    // 2. 检查权限
    if ( ! current_user_can( ‘manage_options’ ) ) {
        wp_die( ‘权限不足！’ );
    }
    // 3. 安全地处理数据…
}

تنظيم الكود والتدويل (Code Organization and Internationalization)

بالنسبة للإضافات المعقدة، يُنصح باستخدام البرمجة الكائنية (Object-Oriented Programming – OOP) لتنظيم الكود، وتقسيم الوظائف إلى كلاسات منفصلة. هذا يعزز قابلية قراءة الكود وإعادة استخدامه.

في الوقت نفسه، يجب الاستعداد مسبقًا لتدويل الإضافات منذ البداية. هذا يعني أن جميع النصوص الموجهة للمستخدمين يجب أن تستخدم دوال الترجمة الخاصة بـ WordPress.__()、_e()قم بالتغليف. إذا نظرت إلى تعليقات بداية الإضافة (plugin header comments)، فقد قمنا بالفعل بتعريف المتطلبات اللازمة.Text Domainيجب استخدامه في الكود بهذه الطريقة:

$message = __( ‘感谢阅读！本文由“我的第一个插件”为您呈现。’， ‘my-first-plugin’ );

ثم، يمكنك استخدام أدوات مثل Poedit لإنشاء ما تحتاجه..potملف قالب، يُستخدم من قبل المترجمين لإنشاء نسخ بلغات مختلفة..moملف.

الملخصات

من خلال هذا الدليل، قمت بإكمال الرحلة الأساسية لإنشاء إضافة (Plugin) لووردبريس من الصفر. لقد تعلمت كيفية إعداد بيئة التطوير، وكيفية إنشاء ملفات الإضافة التي تحتوي على تعليقات الرأس القياسية، وكيفية استخدام نظام الخيوط (Hooks) القوي في ووردبريس لإضافة الميزات. كما ناقشنا كيفية إضافة قوائم الإدارة بشكل آمن، وكيفية معالجة البيانات، وأكدنا على أهمية الأمان والتدويل. تطوير الإضافات هو عملية مستمرة من التعلم والممارسة، والمفتاح هو فهم نظام الخيوط في ووردبريس ومعايير الأمان. في المرحلة التالية، يمكنك محاولة تطوير ميزات أكثر تعقيدًا، مثل إنشاء جداول قواعد البيانات المخصصة، أو إضافة رموز قصيرة (Shortcodes)، أو أدوات (Widgets)، أو نقاط نهاية لواجهات برمجة التطبيقات الخدمية (REST API)، وبذلك بناء إضافات تجارية ذات ميزات متكاملة وكود قوي.

الأسئلة الشائعة الأسئلة المتداولة

هل يجب وضع الإضافة (البرنامج الإضافي) داخل مجلد منفصل؟

لا، يمكن أن يكون الإضافة (plugin) مجرد ملف منفصل بحد ذاته..phpالملفات، يمكن وضعها مباشرةً هناك./wp-content/plugins/موجود داخل المجلد. ومع ذلك، بالنسبة لأي إضافة (plugin) تحتوي على عدة ملفات أو موارد (مثل ملفات JS أو CSS) أو تتطلب ترجمة الملفات، يُنصح بشدة باستخدام مجلد منفصل لتخزين جميع الملفات ذات الصلة. هذا سيجعل هيكل المشروع أكثر وضوحًا وسيسهل عملية الإدارة.

كيف يمكنني حفظ إعدادات الإضافة الخاصة بي في قاعدة البيانات؟

يوفر ووردبريس واجهة برمجة تطبيقات (API) مريحة للغاية. يمكنك استخدامها لتنفيذ مختلف المهام والتعديلات على موقعك الإلكتروني.add_option()、get_option()وupdate_option()توجد دوال لإضافة واسترجاع وتحديث إعدادات الإضافات (plugins). سيتم تخزين هذه البيانات بشكل آمن في نظام ووردبريس (WordPress).wp_optionsفي جداول قواعد البيانات، بالنسبة لكميات كبيرة من البيانات المنظمة، يمكن النظر في تسلسلها إلى مصفوفات أو سلاسل نصية JSON ثم تخزينها.

هل سيتعارض البرنامج المكمل الذي طورته مع برامج مكملة أخرى؟

من الممكن، خاصة عندما تستخدم الإضافات (plugins) أسماء معيارية للدوال (hooks) أو الكلاسات (classes) أو المتغيرات (variables). لتجنب حدوث تعارضات، فإن أفضل الممارسات هي: إضافة بادئة فريدة لجميع الدوال والكلاسات والمتغيرات الخاصة بك (على سبيل المثال، باستخدام اختصار أو اسم الإضافة)، واستخدام اسم الإضافة كمساحة اسم (namespace) (يمكن استخدام المساحات الاسم الحقيقية في PHP 5.3 وما بعدها)، واختيار أولوية مناسبة عند استخدام الدوال المعينة لضمان تنفيذها بالترتيب المتوقع.

ما هي إصدارات ووردبريس التي يجب أن يكون الإضافة متوافقة معها؟

يعتمد الأمر على المستخدمين المستهدفين. عادةً، يُنصح بأن يكون البرنامج متوافقًا مع الإصدارات الرئيسية الحالية بالإضافة إلى إصدار أو إصدارين سابقين. يمكنك ذلك من خلال تحديد متطلبات التوافقreadme.txtمن خلال الملفRequires at least:يجب استخدام الحقول لتحديد الإصدار الأدنى المطلوب من ووردبريس (WordPress). أثناء عملية التطوير، يجب تجنب استخدام الدوال المتوفرة فقط في الإصدارات الأحدث من ووردبريس، أو استخدام ميزات لا تتوافق مع الإصدار الحالي.function_exists()إجراء تقييم للتوافق من أجل توسيع نطاق استخدام الإضافة.