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

عندك سطرين كود في functions.php شايلين ميزة مهمة في الموقع، وكل مرة تحدّث القالب قلبك بيتقبض. أو عميل طالب حاجة صغيرة مفيش إضافة جاهزة بتعملها زي ما هو عايز بالظبط. في الحالتين الحل إنك تعمل إضافتك الخاصة، وده أبسط بكتير مما تتخيل.

هل تحتاج إضافة خاصة أصلًا؟

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

قبل أن تكتب الكود

أين تضع كودك في ووردبريس؟

أربعة خيارات، ولكل منها حالته

المعيار	الأنسب له	العيب
إضافة جاهزة	الاحتياجات الشائعة	تحديثات لا تتحكم فيها
functions.php	تعديل صغير لمرة	يضيع مع تغيير القالب
إضافة إلزامية mu-plugins	كود يجب أن يعمل دائمًا	لا تُعطَّل من اللوحة
إضافة خاصة	منطق تحتفظ به وتنقله	صيانتها عليك

ابن موقعك قطعة قطعةarabcms.com

القاعدة العملية: لو الكود منطق خاص بموقعك وتريد أن يبقى مهما تغيّر القالب، فمكانه إضافة (Plugin) مستقلة. ولو كان يجب أن يعمل دائمًا دون أن يعطّله أحد بالخطأ، فمكانه الإضافة الإلزامية (Must-Use Plugin) في مجلد mu-plugins.

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

كيف تعمل إضافات ووردبريس؟ الخطّافات أولًا

كل إضافة تتحدث مع ووردبريس عبر الخطّافات (Hooks): نقاط داخل كود ووردبريس تسمح لك بربط دالتك بها. وهي نوعان:

• الحدث (Action): يشغّل دالتك عندما يقع شيء، مثل حفظ مقال أو بناء قائمة لوحة التحكم. لا يعيد قيمة.
• المرشِّح (Filter): يستقبل قيمة، فتعدّلها، ثم يجب أن تعيدها. لو نسيت الإرجاع، ستختفي القيمة.

مثال على Filter من سطر واحد يغيّر طول المقتطف إلى 30 كلمة:

add_filter( 'excerpt_length', function ( $length ) {
    return 30;
} );

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

جهّز بيئة العمل قبل أي سطر

لا تبنِ إضافة على موقع حي. استخدم بيئة الاختبار (Staging) أو موقعًا محليًا على جهازك، وأسهل طريقة لذلك تطبيق LocalWP المجاني.

ثم فعّل عرض أخطاء PHP أثناء العمل بإضافة هذا السطر في wp-config.php:

define( 'WP_DEBUG', true );

تنبيه: أعِد القيمة إلى false قبل نقل أي شيء إلى الموقع الحي، فعرض الأخطاء للزوار يكشف مسارات ملفاتك.

خطوات إنشاء إضافة ووردبريس

سنبني مثالًا عمليًا من المصدر: إضافة باسم Content Health Check تفحص المقالات وتجد الناقص منها، مثل مقال بلا صورة بارزة أو بلا تصنيف، أو مسودة عمرها أكثر من 30 يومًا، أو مقال أقل من 600 كلمة.

1. اكتب المشكلة في جملة واحدة

من يحتاج الإضافة؟ وما الذي لا يستطيع فعله الآن؟ ثم اكتب قائمة الميزات. هذه الجملة تمنعك من التوسع في ميزات لا يحتاجها أحد.

2. اختر اسمًا وبادئة

الاسم يجب أن يكون فريدًا: ابحث عنه في Google وفي دليل إضافات ووردبريس. ومنه اشتق بادئة (Prefix) قصيرة تضعها قبل كل دالة لتتجنب تعارض الأسماء مع إضافات أخرى، مثل chc_ لـ Content Health Check.

3. أنشئ المجلد والملف

داخل wp-content/plugins أنشئ مجلدًا باسم الإضافة بحروف صغيرة وشرطات: content-health-check. وبداخله ملف PHP بالاسم نفسه: content-health-check.php.

الإضافة البسيطة قد تكون هذا الملف وحده. الأكبر منها تضيف ملفات CSS وJavaScript وملفات ترجمة في مجلدات فرعية.

4. أضف ترويسة الإضافة

ترويسة الإضافة (Plugin Header) تعليق في أعلى الملف يعرّف ووردبريس بإضافتك. هذا مثال المصدر كاملًا:

<?php
/**
 * Plugin Name: Content Health Check
 * Description: Find common content issues in WordPress posts.
 * Version: 1.1.0
 * Requires at least: 6.0
 * Requires PHP: 7.4
 * Author: Alex Bulat
 * License: GPL-2.0-or-later
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain: content-health-check
 * Domain Path: /languages
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

السطور الثلاثة الأخيرة تمنع فتح الملف مباشرة من المتصفح. وحسب دليل مطوري ووردبريس الرسمي، الحقل الإلزامي الوحيد هو Plugin Name، والباقي اختياري لكنه مفيد:

الحقل	فائدته
Requires PHP	أقل نسخة PHP تحتاجها الإضافة
—	—
Text Domain وDomain Path	ربط النصوص بملفات الترجمة ومكانها
Requires Plugins	إضافات تعتمد عليها، بأسمائها المختصرة (slug) مفصولة بفواصل
Update URI	يمنع تحديثًا من WordPress.org لإضافة باسم مشابه من الكتابة فوق إضافتك

ملاحظة: ضع الترويسة في ملف واحد فقط داخل الإضافة. احفظ الملف وافتح Plugins في لوحة التحكم، وستجد إضافتك في القائمة.

5. أضف الوظائف

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

add_action( 'admin_menu', 'chc_register_page' );

function chc_register_page() {
    add_menu_page(
        __( 'Content Health', 'content-health-check' ),
        __( 'Content Health', 'content-health-check' ),
        'edit_posts',
        'content-health-check',
        'chc_render_page',
        'dashicons-heart'
    );
}

function chc_render_page() {
    if ( ! current_user_can( 'edit_posts' ) ) {
        return;
    }

    $posts = get_posts( array(
        'post_type'   => 'post',
        'post_status' => 'publish',
        'numberposts' => 50,
        'meta_query'  => array(
            array(
                'key'     => '_thumbnail_id',
                'compare' => 'NOT EXISTS',
            ),
        ),
    ) );

    echo '<div class="wrap"><h1>' . esc_html__( 'Posts without a featured image', 'content-health-check' ) . '</h1><ul>';
    foreach ( $posts as $post ) {
        printf(
            '<li><a href="%s">%s</a></li>',
            esc_url( get_edit_post_link( $post->ID ) ),
            esc_html( get_the_title( $post ) )
        );
    }
    echo '</ul></div>';
}

لاحظ ثلاثة أشياء: الـ Action admin_menu يضيف الصفحة، وcurrent_user_can يتحقق من الصلاحية، وesc_html وesc_url يهرّبان كل ما يُطبع. ثم فعّل الإضافة من Plugins > Activate.

هل تستخدم ChatGPT أو Claude لكتابة الكود؟

كاتب المصدر استخدم ChatGPT لكتابة المسودة الأولى، وهذا طبيعي اليوم. لكن الكود المولَّد بالذكاء الاصطناعي ليس آمنًا تلقائيًا، وأكثر ثغراته شيوعًا هي نفسها ثغرات المبتدئين:

• طباعة مدخلات دون تهريب المخرجات (Escaping).
• تنفيذ إجراء دون فحص صلاحية المستخدم بـ current_user_can.
• استقبال نماذج دون رمز التحقق (Nonce) ودون تنظيف المدخلات.

اقرأ كل سطر قبل أن تلصقه، وجرّبه على بيئة الاختبار، ولا تضعه على موقع حي قبل ذلك.

بصراحة: لم نبنِ إضافة Content Health Check الأصلية ولم نختبرها، والهيكل أعلاه مثال توضيحي لا يغطي كل الفحوصات التي يذكرها المصدر.

انقل الإضافة إلى موقع آخر

لو بنيتها محليًا فووردبريس يراها مباشرة. لنقلها إلى موقع آخر، اضغط المجلد نفسه (وليس محتوياته) كملف .zip، بحيث يحتوي الأرشيف على content-health-check/content-health-check.php.

ثم من لوحة الموقع الآخر: Plugins > Add New Plugin > Upload Plugin، اختر الملف، ثم Install Now وActivate.

قائمة الفحص قبل أن تسلّم الإضافة

• بادئة فريدة لكل دالة وثابت.
• الملف الرئيسي باسم الإضافة، وكل ما عداه في مجلدات فرعية بهذا الشكل الذي يوصي به WordPress.org:

/plugin-name
    plugin-name.php
    uninstall.php
    /languages
    /includes
    /admin
        /js
        /css
        /images
    /public
        /js
        /css
        /images

• تهريب كل المخرجات وفحص الصلاحيات في كل إجراء.
• تشغيل إضافة Plugin Check مع WP_DEBUG وإصلاح كل خطأ وتحذير.
• ملف uninstall.php يحذف ما خزّنته الإضافة من إعدادات أو جداول عند حذفها.
• نطاق الترجمة (Text Domain) في كل نص ظاهر للمستخدم.

في ووردبريس: نطاق الترجمة ليس رفاهية لو عملاؤك عرب. هو ما يسمح بتعريب واجهة الإضافة دون لمس الكود، ومعه اختبر صفحات الإضافة ولوحة التحكم بالعربية واتجاه RTL قبل التسليم.

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

س: هل أضع الكود في functions.php أم في إضافة؟
ج: في إضافة إذا كان منطقًا تريد أن يبقى. كود functions.php مرتبط بالقالب، فيضيع إذا غيّرته، وأي خطأ PHP فيه قد يوقف الموقع كله.

س: هل أحتاج ترخيصًا لإضافتي؟
ج: لا إن كانت لاستخدامك الخاص. أما إن نشرتها للعامة، فيجب أن تكون متوافقة مع رخصة GPL الإصدار الثاني أو أحدث.

س: ما المهارات المطلوبة لإنشاء إضافة ووردبريس؟
ج: PHP أساسًا، مع HTML وCSS وJavaScript وأساسيات SQL. ولبناء بلوكات للمحرر ستحتاج JavaScript وReact.

س: كيف أحذف بيانات إضافتي عند إزالتها؟
ج: أضف ملف uninstall.php يحذف الإعدادات أو الجداول التي أنشأتها الإضافة، فيعمل تلقائيًا عند حذفها من لوحة التحكم.

الخلاصة

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

ولو عندك فكرة إضافة لموقعك أو لعميل ومحتاج حد يراجع الكود قبل ما ينزل، احجز استشارة مجانية“>تواصل معنا من هنا.

مراجع إضافية: Header Requirements — Plugin Handbook

مرجع المقال (بالإنجليزية): A Beginner’s Guide for WordPress Plugin Development (2026)
المقال ده مش ترجمة حرفية: متكيّف للقارئ العربي ومضاف عليه سياق ووردبريس وElementor وJetEngine.