شكل البداية/المتعلقة بالمعرفة/ووردبريس/تفاصيل المحتوى

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

قراءة 3 دقائق
2026-03-13
2026-06-03
1,934
أنا أحصل على عمولة عند التسوق عبر الروابط أدناه، ولا يُضاف أي تكلفة عليك.

الاستعدادات وإعداد البيئة.

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

أولاً، يجب عليك تثبيت بيئة خادم ويب على جهاز الكمبيوتر الخاص بك، والتي تُعرف عادةً باسم “بيئة الخادم المحلي”. من بين الخيارات الأكثر شيوعًا XAMPP أو MAMP، والتي تجمع بين مكونات Apache وMySQL/MariaDB وPHP. كما أن استخدام Docker يعد حلاً قويًا لإعداد بيئة قريبة من بيئة الإنتاج. بغض النظر عن الخيار الذي تختاره، تأكد من أن إصدار PHP الخاص بك (يُنصح باستخدام إصدار 7.4 أو أحدث) وإصدار MySQL متوافقان مع معظم بيئات استضافة WordPress.

بعد ذلك، قم بتنزيل أحدث إصدار من WordPress وتثبيته. قم بفك ضغط ملفات WordPress في المجلد الرئيسي لموقعك على الخادم المحلي الخاص بك (مثل المجلد الرئيسي لـ XAMPP). htdocs قم بإنشاء مجلد (folder) واتبع الإجراءات المعروفة لـ “التثبيت في خمس دقائق” (five-minute installation process) لإكمال الإعدادات. تأكد من أنك قادر على الوصول إلى موقع WordPress المحلي بشكل صحيح.

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

وأخيرًا، وهو الخطوة الأكثر أهمية: قم بتحضير محرر كود. ننصح باستخدام محررات مثل Visual Studio Code أو PhpStorm أو Sublime Text، والتي تتميز بإمكانيات تمييز الكود بألوان مختلفة، وتقديم اقتراحات ذكية أثناء الكتابة، بالإضافة إلى إمكانيات التصحيح والتحقيق من أخطاء الكود. هذه الميزات مفيدة بشكل خاص عند التطوير باستخدام لغة PHP، حيث يمكن أن تساعدك في تجنب العديد من الأخطاء النحوية البسيطة.

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

هيكلية الإضافة الأساسية والملف الرئيسي

يحتوي إضافة ووردبريس (WordPress plugin) على هيكل ملفات قياسي وضروري، وجوهرها يتكون من ملف يقع في… /wp-content/plugins/ المجلد ذو نفس الاسم الموجود في المسار، بالإضافة إلى الملف الرئيسي للغة PHP الموجود داخل ذلك المجلد.

إنشاء الملف الرئيسي للإضافة (plugin)

أولاً، في… /wp-content/plugins/ قم بإنشاء مجلد جديد داخل الدليل، يجب أن يكون اسم المجلد موجزًا وفريدًا ويوضح وظيفة الإضافة (plugin)، مثل “my-first-plugin”. بعد ذلك، قم بإنشاء ملف PHP باسم نفس اسم المجلد داخل هذا المجلد. my-first-plugin.php。

هذا الملف الرئيسي يمثل “نقطة الدخول” للإضافة (plugin)، حيث يقوم ووردبريس (WordPress) بقراءة معلومات رأس الإضافة (plugin header) الموجودة في بداية الملف للتعرف على بيانات الوصف (metadata) الخاصة بها. معلومات رأس الإضافة عبارة عن كتلة تعليقات قياسية في لغة PHP، ويجب وضعها في بداية الملف مباشرةً. يجب أن تحتوي هذه المع

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

في الكود المذكور أعلاه،Plugin Name هذه المعلومات إلزامية، بينما المعلومات الأخرى اختيارية ولكن يُنصح بتعبئتها. ستظهر هذه المعلومات في صفحة إدارة الإضافات (Plugins) في واجهة ووردبريس الخلفية.Text Domain يُستخدم للتدويل (دعم اللغات المتعددة)، ويتوافق مع نطاق النصوص المستخدم عند استدعاء دوال الترجمة لاحقًا.

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

تعريف الثوابت الأساسية للإضافة (Plugin)

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

يمكنك إضافة الكود التالي إلى الملف الرئيسي، مباشرة بعد معلومات رأس الإضافة (plugin header)، لتعريف الثوابت (constants):

// 防止直接访问
if ( ! defined( 'ABSPATH' ) ) {
    exit; // 如果 ABSPATH 未定义，则退出
}

// 定义插件路径和URL常量
define( 'MFP_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
define( 'MFP_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
define( 'MFP_PLUGIN_VERSION', '1.0.0' );

هنا،plugin_dir_path( FILE ) و plugin_dir_url( FILE ) هذه دالة أساسية مقدمة من ووردبريس (WordPress)، تسمح بالحصول بشكل آمن على مسار المجلد الخاص بملف الإضافة (plugin) الحالي وعلى عنوان URL الخاص به.MFP_PLUGIN_VERSION تُستخدم الثوابت لتخزين أرقام إصدارات الإضافات (البرامج الإضافية)، مما يسهل عملية استيراد أنماط النصوص (scripts) أو مقارنة إصدارات الإضافات نفسها.

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

تنفيذ الميزات الأساسية واستخدام الخطافات (hooks)

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

أضف خطافًا بسيطًا للإجراء (action hook).

دعونا نطبق أبسط ميزة ممكنة: إضافة سطر نصي إلى قسم القائمة في صفحة الموقع. سنستخدم "خطافات الإجراءات" (action hooks) لتحقيق ذلك. wp_footerسيتم تنفيذه قبل إظهار النص HTML في منطقة القائمة السفلية (التي تُعرف بـ "القدم" من الصفحة).

أضف دالة في الملف الرئيسي، ثم استخدمها من خلال… add_action تقوم الدالة بتثبيته (أو تركيبه) هناك. wp_footer على هذا الخطاف.

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

/**
 * 在网站页脚输出自定义文本
 */
function mfp_display_footer_text() {
    echo '<p style="text-align: center; color: #666;">شكرًا لاستخدام أول إضافة (Plugin) لي لموقع ووردبريس (WordPress) الخاص بي!</p>';
}
add_action( 'wp_footer', 'mfp_display_footer_text' );

الآن، قم بتفعيل الإضافة (البرنامج الإضافي) الخاصة بك، ثم قم بزيارة واجهة الموقع الإلكتروني وانزلق إلى أسفل الصفحة؛ يجب أن تتمكن من رؤية هذا النص. هذا هو المثال الأساسي لكيفية استخدام “خطاف

استخدم المرشحات لتعديل المحتوى.

تُستخدم المرشحات (filters) لتعديل قيم موجودة مسبقًا. على سبيل المثال، إذا أردنا تعديل عناوين المقالات بإضافة كلمة “【موصى به】” قبل كل عنوان، فيمكننا تحقيق ذلك من خلال استخدام المرشحات المناسبة. the_title يتم تنفيذ ذلك باستخدام مرشحات (filters).

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

قم بإنشاء دالة جديدة تتلقى عنوانًا أصليًا يجب تصفيته كمعامل، وتعيد عنوانًا معدلًا، ثم… add_filter تم التثبيت.

/**
 * 在所有文章标题前添加前缀
 * @param string $title 原始标题
 * @return string 修改后的标题
 */
function mfp_add_prefix_to_title( $title ) {
    // 确保只在主循环中修改，避免影响后台列表等其他地方
    if ( is_single() && in_the_loop() ) {
        $title = '【推荐】' . $title;
    }
    return $title;
}
add_filter( 'the_title', 'mfp_add_prefix_to_title' );

هذا المثال البسيط يوضح قوة المرشحات (الفلاتر): يمكنك فحص الشروط (مثل…) is_single() تحديد ما إذا كانت الصفحة تمثل مقالة واحدة فقط، وإجراء التعديلات فقط على المحتوى الموجود في سياق معين.

إضافة صفحات الإدارة وممارسات الأمان

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

صفحة إعدادات إنشاء الإضافة

سنستخدم… add_menu_page تقوم الدالة بإضافة قائمة إدارية رئيسية للإضافة (plugin) بالإضافة إلى صفحة الإعدادات المقابلة لها.

أولاً، قم بإنشاء دالة لتوليد محتوى HTML الخاص بصفحة الإعدادات، ثم قم بتثبيت هذه الدالة على الصفحة المطلوبة. admin_menu استخدم دالة خاصة بخطافات الأفعال (action hooks) لتسجيل هذا القائمة.

/**
 * 渲染插件设置页面的HTML内容
 */
function mfp_render_settings_page() {
    // 检查用户权限
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( __( '你没有足够的权限访问此页面。', 'my-first-plugin' ) );
    }
    ?&gt;
    <div class="wrap">
        <h1></h1>
        <p>هذه هي صفحة إعدادات الإضافة الخاصة بي. في المستقبل، يمكننا إضافة نماذج وخيارات إلى هنا.</p>
        <form action="/ar/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 后续可以在这里添加设置字段
            // settings_fields( 'mfp_options_group' );
            // do_settings_sections( 'mfp-settings-page' );
            // submit_button( '保存设置' );
            ?>
        <input type="hidden" name="trp-form-language" value="ar"/></form>
    </div>
    &lt;?php
}

/**
 * 注册插件管理菜单
 */
function mfp_add_admin_menu() {
    add_menu_page(
        &#039;我的第一个插件设置&#039;, // 页面标题
        &#039;我的插件&#039;,          // 菜单标题
        &#039;manage_options&#039;,    // 所需权限 (manage_options)
        &#039;mfp-settings-page&#039;, // 菜单slug
        &#039;mfp_render_settings_page&#039;, // 回调函数
        &#039;dashicons-admin-plugins&#039;, // 图标 (Dashicons)
        80                   // 菜单位置
    );
}
add_action( &#039;admin_menu&#039;, &#039;mfp_add_admin_menu&#039; );

بعد تفعيل الإضافة، سترى خيارًا جديدًا يسمى “إضافاتي” (My Plugins) في الجانب الأيسر من واجهة ووردبريس الخلفية. عند النقر عليه، ستدخل إلى صفحة إعدادات بسيطة. تم تخصيص هذه الصفحة لاستخدام واجهة برمجة تطبيقات ووردبريس (WordPress Settings API) لإضافة حقول نموذج (form fields)، وهي الطريقة القياسية لمعالجة مدخلات المستخدمين بشكل آمن.

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

يجب معالجة أي بيانات تُستلم من المستخدمين أو تُرسل إلى المتصفح لمنع هجمات الكود الخبيث عبر المواقع (XSS) وهجمات حقن SQL. يوفر ووردبريس مجموعة واسعة من الدوال الأمنية لتسهيل هذه المهام.

  • إخراج الكود المهرب: استخدم Escape output: Use < esc_html()、esc_attr()、esc_url() و wp_kses_post() استخدم دوال مثل هذه لتنقية المحتوى الذي يتم عرضه في HTML.
  • التحقق من صحة البيانات: الاستخدام sanitize_text_field()、sanitize_email() استخدم دوال مثل هذه لتنظيف البيانات المقدمة من النموذج.
  • مفتاح غير CE: يجب استخدامه في عمليات النماذج التي تتضمن تعديل البيانات. wp_nonce_field() و wp_verify_nonce() للتحقق من شرعية الطلب.

الأمان هو العمود الفقري في تطوير الإضافات (البرامج الإضافية)، ويجب تكوين عادات جيدة منذ البداية.

الملخصات

من خلال هذا الدليل، أكملنا عملية تطوير إضافة (plugin) لووردبريس كاملة ومتكاملة، رغم صغر حجمها. بدأنا من الصفر، حيث أنشأنا بيئة التطوير اللازمة وقمنا بإنشاء هيكل الملفات الرئيسية للإضافة وفقًا للمعايير المعتمدة. كما فهمنا بعمق كيفية استخدام “مخالب الأفعال” (action hooks) و“مخالب المرشحات” (filter hooks)، وهي الأدوات الأساسية التي يعتمد عليها ووردبريس في عمله، من خلال تنفيذ وظيفتين محددتين: إضافة نص إلى القسم السفلي من الصفحة وتعديل عناوين المقالات. وأخيرًا، أضفنا صفحة إدارة أساسية للإضافة في الواجهة الخلفية، مع التأكيد على أهمية ممارسات الأمان مثل التحقق من صحة البيانات (data validation)، ومراقبة الصلاحيات (permission checking

هذا الإضافة البسيطة من نوع “Hello World” تحتوي بالفعل على العناصر الأساسية اللازمة للإضافات التجارية: الهيكل القياسي، استخدام الـ “hooks”، واجهة الخلفية، والاعتبارات الأمنية. باستخدام هذا كنقطة انطلاق، يمكنك محاولة دمج واجهة برمجة التطبيقات (API) الخاصة بإعدادات ووردبريس (WordPress Settings API) لإنشاء خيارات حقيقية، أو كتابة جداول قواعد البيانات المخصصة، أو إنشاء أكواد قصيرة وأدوات مفيدة أكثر تعقيدًا. تذكر أن المواصلة في دراسة الكتيبات الرسمية للتطوير ومراجعة كود الإضافات المفتوحة المصدر عالية الجودة هي أفضل طريقة لتحسين مهاراتك.

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

كيف يمكنني تصحيح أخطاء (الديباجات) في إضافة ووردبريس الخاصة بي (####)؟
الخطوة الأولى هي تفعيل وضع التصحيح (Debugging Mode) في ووردبريس. في موقعك… wp-config.php في الملف، سيتم… WP_DEBUG تم تعيين قيمة الثابتة كـ trueيمكنك أيضًا إجراء بعض التعديلات الإضافية. WP_DEBUG_LOG لأجل trueقم بتسجيل رسائل الخطأ في… /wp-content/debug.log في الملفات، يجب تجنب عرض رسائل الخطأ مباشرة على الصفحة لكي لا تؤثر سلبًا على المستخدمين.

بالإضافة إلى ذلك، استخدام أداة مطوري المتصفحات (F12) ولوحتي Console وNetwork لعرض أخطاء JavaScript وطلبات الـ API، بالإضافة إلى استخدام أدوات تصحيح أخطاء PHP مثل Xdebug مع محرر الكود الخاص بك (مثل VS Code) لإجراء التصحيح التدريجي (debugging with breakpoints)، كلها وسائل فعالة للغاية للتصحيح الاحترافي.

لماذا يظهر رسالة “خطأ فادح” عند تفعيل إضافتي؟

عادةً ما يحدث هذا بسبب خطأ في صيغة لغة PHP أو استدعاء لدالة/فئة غير موجودة. أولاً، قم بفحص سجلات التصحيح (debug logs) الخاصة بووردبريس (كما ذكر أعلاه)؛ فإن رسائل الخطأ ستوضح بشكل دقيق أي ملف وأي سطر هو المشكلة.

الأسباب الشائعة تشمل: عدم وجود علامات الفاصلة (؛)، أو عدم تطابق أقواس الفتح والإغلاق، أو استدعاء دالة دون تضمين الملفات الضرورية، أو محاولة تشغيل كود بعد تعطيل الإضافات (plugins). تأكد من أن إصدار PHP الخاص بك مطابق للمتطلبات، وأن جميع الدوال معرفة (مُعرّفة بشكل صحيح) قبل استخدامها.

كيف يمكنني جعل إضافتي تدعم عدة لغات (التدويل)؟

يستخدم WordPress إطار عمل GNU gettext لتحقيق التدويل (i18n) والتكييف المحلي (l10n). أولاً، كما هو موضح في الدروس، يجب ضبط الإعدادات بشكل صحيح في معلومات رأس الملف الرئيسي. Text Domain(على سبيل المثال، my-first-pluginو Domain Path。

في كود الإضافة (البرنامج المساعد)، يجب تغليف جميع النصوص التي تحتاج إلى ترجمة باستخدام دالة الترجمة المناسبة. على سبيل المثال:__( ‘文本’, ‘my-first-plugin’ ) أو _e( ‘文本’, ‘my-first-plugin’ )ثم، استخدم أداة مثل Poedit لمسح هذه السلاسل النصية داخل الكود، وإنشاء ملف قالب بصيغة .pot، وبعد ذلك قم بإنشاء ملفات .po و.mo الخاصة باللغة المطلوبة (مثل الصينية zh_CN)، وضعها في المكان المناسب. /languages/ تحت القائمة.

كيف يمكن التفاعل بأمان مع قاعدة البيانات أثناء تطوير الإضافات (البرامج الإضافية)؟

لا تقم أبدًا بكتابة جمل SQL مباشرةً لدمج المدخلات من المستخدمين. يجب استخدام الفئات المتاحة في WordPress للتعامل مع قواعد البيانات. $wpdbيوفر ما يشبه… $wpdb->prepare() يمكن لهذه الطريقة معالجة استعلامات SQL باستخدام جمل تحضيرية آمنة، مما يساعد بشكل فعال على منع هجمات الاستيلاء على بيانات SQL (SQL Injection).

على سبيل المثال، يجب كتابة الاستعلام عن البيانات بالطريقة التالية:

global $wpdb;
$user_input = $_POST['some_input'];
$safe_query = $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}table WHERE column = %s", $user_input );
$results = $wpdb->get_results( $safe_query );

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

ما التالي، ما التالي؟

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

القراءة الموسعة والمعرفة العملية

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

الوسوم