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

الاستعدادات وتكوين البيئة

قبل البدء في كتابة الكود، من الضروري للغاية إنشاء بيئة تطوير محلية متخصصة. هذا لا يساعد فقط على تحسين كفاءة عملية التطوير، ولكنه أيضًا يمنع المخاطر التي قد تنشأ أثناء إجراء الاختبارات على الخوادم عبر الإنترنت. يُنصح باستخدام برامج خادم محلية مدمجة مع Apache/Nginx وMySQL وPHP، مثل Local by Flywheel أو XAMPP أو MAMP. تأكد من أن إصدار PHP الخاص بك متوافق مع بيئة WordPress المستهدفة؛ عادةً ما يُنصح باستخدام إصدار PHP 7.4 أو أحدث.

أنت بحاجة إلى محرر كود، مثل Visual Studio Code أو PhpStorm أو Sublime Text. توفر هذه المحررات عادةً تمييزًا للغة البرمجية، واقتراحات أثناء كتابة الكود، بالإضافة إلى تكامل مع أنظمة إدارة الإصدارات (Version Control)، مما يحسن بشكل كبير تجربة البرمجة. كما أن الإلمام بدليل تطوير الإضافات الرسمي لـ WordPress ووثائق معايير الكتابة الخاصة بها أمر أساسي لتطوير إضافات عالية الجودة؛ حيث يجب اتباع هذه المعايير (مثل استخدام أسماء معينة كبادئات لتجنب تعارض أسماء الدوال).

فهم البنية الأساسية للإضافات.

يمكن أن يتكون أبسط إضافة (plugin) لـ WordPress من ملف رئيسي واحد فقط. تسمية هذا الملف الرئيسي مهمة للغاية، وعادة ما تكون مرتبطة بوظيفة الإضافة نفسها؛ على سبيل المثال: my-custom-plugin.phpيجب أن يحتوي بداية الملف على تعليق يحمل رأس الإضافة (plugin header) وفقًا لتنسيق معين، وهو أمر أساسي لكي يتمكن ووردبريس (WordPress) من التعرف على الإضافة.

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

توفر تعليقات رأس الإضافة (plugin header comments) معلومات أساسية عن الإضافة، مثل الاسم والوصف والإصدار والمؤلف، وما إلى ذلك. فيما يلي مثال على رأس إضافة قياسي:

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

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

صفحة الوصول

<?php
/**
 * Plugin Name:       我的自定义功能扩展
 * Plugin URI:        https://example.com/my-custom-plugin
 * Description:       这是一个用于演示的 WordPress 自定义插件。
 * Version:           1.0.0
 * Author:            你的名字
 * Author URI:        https://example.com
 * License:           GPL v2 or later
 * Text Domain:       my-custom-plugin
 * Domain Path:       /languages
 */

التطوير الأساسي: خطافات الأفعال والمرشحات (Core Development: Action and Filter Hooks)

جوهر تطوير إضافات ووردبريس (WordPress plugins) يكمن في فهم واستخدام نظام “الخطافات” (Hooks) الخاص به. تنقسم الخطافات إلى نوعين: الإجراءات (Actions) والمرشحات (Filters). تسمح الإجراءات (Actions) بتنفيذ كود مخصص في نقاط معينة من دورة حياة ووردبريس، مثل عملية التهيئة (Initialization)، تحميل الصفحات (Page Loading)، أو نشر المقالات (Article Publishing). أما المرشحات (Filters) فتسمح بتعديل البيانات الناتجة أثناء تشغيل ووردبريس أو الإضافات الأخرى.

استخدم خطافات الحركة لإضافة وظائف.

تتم عملية تنفيذ “خطافات الإجراءات” (Action Hooks) من خلال… add_action() تثبيت الدوال (Function Mounting). على سبيل المثال، إذا كنت ترغب في إضافة إشعار مخصص في الجزء العلوي من واجهة إدارة الموقع الإلكتروني، فيمكنك استخدام هذه الطريقة. admin_notices هذا هو “خطاف الإجراء” (action hook). يجب عليك إنشاء دالة لإخراج محتوى الإشعار، ثم تثبيت هذه الدالة على الخطاف المعني.

في المثال أدناه، قمنا بإنشاء دالة. my_custom_admin_notice أريد إخراج رسالة تحذير بسيطة، وذلك من خلال add_action قم بربطها بـ admin_notices خطاف.

function my_custom_admin_notice() {
    echo '<div class="notice notice-success is-dismissible"><p>تم تفعيل الإضافة المخصصة الخاصة بي بنجاح!</p></div>';
}
add_action( 'admin_notices', 'my_custom_admin_notice' );

استخدم خطافات المرشحات (filter hooks) لتعديل المحتوى.

تم تنفيذ خطوات تثبيت خطافات المرشحات (filter hooks) بنجاح. add_filter() تُعرف هذه العملية بـ "تثبيت الدالة" (Function Mounting)، وهي تُستخدم لتعديل البيانات المُمررة إليها. مثال شائع على ذلك هو تعديل نهاية محتوى المقالة لإضافة إعلان حقوق النشر تلقائيًا.

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

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

function append_copyright_to_content( $content ) {
    if ( is_single() ) { // 仅在单篇文章页面生效
        $copyright = '<p><em>© 2026 جميع الحقوق محفوظة. تم إنشاء هذا المقال بواسطة "My Plugin".</em></p>';
        $content .= $copyright;
    }
    return $content;
}
add_filter( 'the_content', 'append_copyright_to_content' );

إنشاء صفحة إدارة وخيارات تهيئة

تحتاج العديد من الإضافات (البرامج الإضافية) إلى توفير واجهة للتكوين للمستخدمين، وعادةً ما يتم تحقيق ذلك عن طريق إضافة صفحة إعدادات مستقلة في واجهة خلفية ووردبريس (WordPress backend). يوفر ووردبريس مجموعة واسعة من واجهات برمجة التطبيقات (APIs) لتسهيل هذه العملية. add_menu_page() و add_options_page()。

أضف قائمة إدارية رئيسية.

الاستفادة من add_menu_page() يمكن للدالة أن تقوم بإنشاء عنصر قائمة رئيسي لإضافتك (plugin). ستحتاج إلى تحديد عناوين الصفحات، عناوين القوائم، صلاحيات المستخدمين، أسماء مستعارة للقوائم، ودوال تعديل (callbacks) لعرض محتوى الصفحة

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

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

صفحة الوصول

الكود أدناه يوضح كيفية إنشاء صفحة قائمة رئيسية تسمى “إعدادات الإضافة الخاصة بي”. (The code below demonstrates how to create a main menu page called “My Plugin Settings”.) render_my_plugin_settings_page مسؤول عن إنتاج محتوى HTML لهذه الصفحة.

الوظيفة my_plugin_add_menu_page() {
    add_menu_page(
        'إعدادات مكوّني الإضافي'،   // عنوان الصفحة
        'مكوّني الإضافي'،   // عنوان القائمة
        'manage_options'،   // الأذونات المطلوبة للمستخدم
        'my-plugin-settings'،   // اسم الوصلة (slug)
        'render_my_plugin_settings_page'،   // الدالة
        'dashicons-admin-generic'،   // الأيقونة (اختياري)
        30   // موضع القائمة (اختياري)
    );
}
add_action( 'admin_menu'، 'my_plugin_add_menu_page' );

function render_my_plugin_settings_page() {
    ?>
    <div class="wrap">
        <h1>إعدادات الإضافة الخاصة بي</h1>
        <form method="post" action="/ar/options.php/" data-trp-original-action="options.php">
            
        <input type="hidden" name="trp-form-language" value="ar"/></form>
    </div>
    أنا لا أعرف ماذا أقول.

حقول إعدادات التسجيل والتحقق

لحفظ مدخلات المستخدمين بشكل آمن، يجب استخدام واجهة برمجة التطبيقات (API) المتاحة في ووردبريس. وهذا يشمل استخدام… register_setting()、add_settings_section() و add_settings_field() وظائف مثل… عند إعداد واجهة برمجة التطبيقات (API)، يتم التعامل تلقائيًا مع التحقق من البيانات، وفحص الطلبات غير الآمنة (nonce)، وتخزين البيانات في قاعدة البيانات.

الكود أدناه يوضح كيفية تسجيل مجموعة إعدادات، ومنطقة إعدادات، وحقل إدخال نصوص. الدالة (function) المستخدمة في الكود مسؤولة عن إجراء عمليات التسجيل هذه. sanitize_my_setting يُستخدم لتنظيف والتحقق من بيانات المستخدم قبل حفظها في قاعدة البيانات.

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

function my_plugin_settings_init() {
    // 注册一个设置
    register_setting( 'my_plugin_settings_group', 'my_plugin_option_name', 'sanitize_my_setting' );

// 添加一个设置区域
    add_settings_section(
        'my_plugin_main_section',
        '主要设置',
        null, // 可选的区域描述回调函数
        'my-plugin-settings'
    );

// 在区域内添加一个字段
    add_settings_field(
        'my_plugin_text_field',
        '示例文本字段',
        'my_plugin_text_field_callback',
        'my-plugin-settings',
        'my_plugin_main_section'
    );
}
add_action( 'admin_init', 'my_plugin_settings_init' );

function sanitize_my_setting( $input ) {
    // 清理输入，例如移除 HTML 标签
    return sanitize_text_field( $input );
}

function my_plugin_text_field_callback() {
    $value = get_option( 'my_plugin_option_name', '默认值' );
    echo '<input type="text" name="my_plugin_option_name" value="' . esc_attr( $value ) . '" class="regular-text" />';
}

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

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

تم تحقيق دعم لترجمة النصوص.

تستخدم ووردبريس إطار عمل GNU gettext لتحقيق التدويل (الترجمة إلى لغات أخرى). يجب أن تغلف جميع النصوص التي تظهر للمستخدمين داخل الإضافات (البرامج الإضافية) باستخدام دوال معينة. أكثر هذه الدوال شيوعًا هي… (The most commonly used functions are…) __()(يُستخدم لإرجاع النص المترجم) و _e()(يُستخدم لعرض النص المترجم مباشرةً.) كما يجب عليك ضبط الإعدادات بشكل صحيح في رأس الإضافة (plugin header). Text Domain و Domain Pathواستخدم أيضًا… load_plugin_textdomain() تقوم الدالة بتحميل ملفات الترجمة في الوقت المناسب.

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

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

صفحة الوصول

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

function my_plugin_load_textdomain() {
    load_plugin_textdomain( 'my-custom-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
}
add_action( 'init', 'my_plugin_load_textdomain' );

// 在需要的地方使用翻译函数
$greeting = __( '你好，世界！', 'my-custom-plugin' );
_e( '这是一个直接输出的消息。', 'my-custom-plugin' );

اتباع المعايير الأساسية للأمان

أمان الإضافات (plugins) يعتبر من الأمور الأساسية جدًا أثناء عملية التطوير. يجب التحقق من جميع المدخلات الواردة من المستخدمين وتنقيتها. عملية التحقق (Validation) تهدف إلى التأكد من أن البيانات تتوافق مع الصيغ المتوقعة (مثل ما إذا كانت عنوان بريد إلكتروني صح filter_var() توجد العديد من الدوال في ووردبريس لتنظيف البيانات (Sanitization)، وهي عملية إزالة الأحرف غير الآمنة منها. يوفر ووردبريس مجموعة واسعة من الدوال لهذا الغرض، مثل… sanitize_text_field()、esc_html()、esc_url() إلخ.

عند إرسال أي بيانات إلى المتصفح، يجب تنفيذ عملية التهريب (Escaping) لمنع هجمات السكريبتات عبر المواقع (XSS – Cross-Site Scripting). يمكن استخدام دوال مختلفة لتنفيذ هذه العملية بشكل صحيح. esc_html()、esc_attr()、wp_kses_post()عند تنفيذ عمليات على قاعدة البيانات، يجب استخدام… $wpdb استخدم الفئات وأوامر المعالجة المسبقة لمنع هجمات الاستيلاء على البيانات من نوع SQL (SQL Injection). لا تقم أبدًا بدمج مدخلات المستخدمين مباشرةً في استعلامات SQL.

الملخصات

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

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

ما هي الحد الأدنى لعدد الملفات المطلوبة لإنشاء إضافة (plugin)؟

يمكن أن يحتوي إضافة ووردبريس (WordPress plugin) كاملة الوظائف على ملف PHP واحد فقط. طالما أن هذا الملف يحتوي على تعليقات رأس الإضافة (Plugin Header) الصحيحة، سيتم التعرف عليها من قبل ووردبريس كإضافة مستقلة. بالطبع، مع تعقيد الوظائف، قد تقوم بتقسيم الكود إلى عدة ملفات، بالإضافة إلى تضمين موارد مثل CSS وJavaScript والصور.

كيف يمكن منع تعارض أسماء دوال الإضافات (plugins) مع إضافات أخرى؟

توصي ووردبريس رسميًا باستخدام بادئة فريدة لتسمية جميع الدوال (functions) والفئات (classes) والمتغيرات (variables) والثوابت (constants) الخاصة بك. عادةً ما تكون هذه البادئة مرتبطة باسم الإضافة (plugin) الخاصة بك أو اسم شركتك، ويجب أن تكون فريدة بما فيه الكفاية. على سبيل المثال، إذا كان اسم إضافتك “Awesome Slider”， فيمكنك استخدام بادئة مثل “AWESOME_Slider_” aslider_init()、ASLIDER_VERSION هذا الأسلوب في التسمية… هناك طريقة أكثر حداثة وأناقة، وهي استخدام مساحات الأسماء (Namespaces) في PHP، والتي يمكن أن تحل مشكلة تعارض الأسماء من جذورها.

ما الذي يجب أن يحدث عند تفعيل الإضافة (البرنامج الإضافي)؟

تعتبر عملية تفعيل الإضافة (plugin activation) فرصة مثالية لتنفيذ مهام إعدادات مرة واحدة. يمكنك تحقيق ذلك عن طريق تسجيل خطاف تفعيل (activation hook). قم بإنشاء دالة تقوم فيها بفحص توافق البيئة (مثل إصدار PHP)، وإنشاء أو تحديث الجداول الضرورية في قاعدة البيانات، وتهيئة القيم الافتراضية لخيارات الإضافة، وما إلى ذلك. register_activation_hook( FILE, ‘your_setup_function’ ) لربط هذه الدالة.

كيف يمكنني أن أجعل المستخدمين يقومون بإزالة إضافتي بشكل آمن؟

لتوفير تجربة مستخدم كاملة، يجب أن يكون قادرًا على تنظيف البيانات التي أنشأها بنفسه. يمكن تحقيق ذلك عن طريق تسجيل “خطاف للإزالة” (uninstallation hook). يوفر ووردبريس طريقتين للإزالة: register_uninstall_hook( FILE, ‘your_cleanup_function’ ) الدالة المسجلة ستتم تنفيذها عندما يقوم المستخدم بالنقر على زر “حذف” الإضافة. داخل هذه الدالة، يمكنك حذف جميع خيارات قاعدة البيانات التي أنشأتها الإضافة، وجداول قاعدة البيانات المخصصة، وما إلى ذلك بشكل آمن. يرجى ملاحظة أ register_deactivation_hook لإجراء عملية حذف دائم للبيانات، لأن تعطيل الخدمة لا يعني بالضرورة إزالتها من النظام.