إدارة التبعيات عبر Composer في إضافات ووردبريس: حل تعارض النسخ وتقنية PHP-Scoper

ما هو جحيم التبعيات (Dependency Hell) في بيئة ووردبريس؟

السبب الجوهري للأزمة دي بيعود للبنية التحتية لمحرك PHP؛ محرك PHP في الذاكرة بيسمح بوجود نسخة واحدة فقط من كل كلاس بنفس الاسم وفضاء الأسماء خلال دورة حياة الريكوست.

لما مبرمج إضافة يكتب في ملفه:

composer require firebase/php-jwt

وبعدين يرفع مجلد vendor/ مع الإضافة ويسيب فضاء الأسماء الأصلي FirebaseJWTJWT زي ما هو، هو كده حط لغم في موقع العميل! لو جه مبرمج تاني في إضافة تانية واستخدم نفس المكتبة لكن بإصدار مختلف فيه تعديل في الـ Signature بتاع الدوال (Breaking Changes)، الإضافة التانية هتفشل وتوقف الموقع فوراً.

تقنية عزل التبعيات (Namespace Prefixing & Scoping)

الفكرة الهندسية العبقرية وراء أدوات مثل **PHP-Scoper** أو **Strauss** هي تحويل الكود البرمجي للمكتبات الخارجية تلقائياً أثناء مرحلة التجهيز (Build Phase):

لو أنت مثبت مكتبة GuzzleHttpClient في إضافتك MyAwesomePlugin:
الأداة بتفتح كل ملفات المكتبة وتعمل لها Refactoring تلقائي، وتغير اسم الكلاس ليصبح:

MyAwesomePluginVendorGuzzleHttpClient

وتغير كل الاستدعاءات والـ Namespaces والـ Use Statements داخل ملفات المكتبة دي ليتطابق مع المسار الجديد!

النتيجة الساحرة:
لو الموقع عليه 10 إضافات مختلفة وكل إضافة فيهم بتستخدم إصدار مختلف من Guzzle، كل إضافة هتشتغل بمكتبتها المعزولة الخاصة بيها في الذاكرة كأنها كلاس مختلف تماماً، ولن يحدث أي تصادم أو Fatal Error إطلاقاً!

التطبيق العملي خطوة بخطوة باستخدام أداة Strauss

أداة Strauss تعتبر من أسهل وأروع الأدوات المخصصة لمطوري ووردبريس، لأنها مصممة خصيصاً للتكامل السلس مع Composer وتعديل ملفات الـ Vendor بضغطة زر واحدة بدون الحاجة لكتابة إعدادات Docker أو Phar معقدة.

الخطوة 1: تهيئة ملف composer.json مع إعدادات Strauss

تنشئ ملف composer.json في مجلد إضافتك وتحدد الحزم المطلوبة وإعدادات البادئة:

{
    "name": "abozaid/enterprise-booking-engine",
    "description": "نظام حجز فندقي متكامل معزول التبعيات",
    "type": "wordpress-plugin",
    "require": {
        "php": ">=8.1",
        "firebase/php-jwt": "^6.8",
        "monolog/monolog": "^3.4"
    },
    "require-dev": {
        "brianhenryie/strauss": "^0.16.0"
    },
    "autoload": {
        "psr-4": {
            "AbozaidBookingEngine": "src/"
        }
    },
    "scripts": {
        "prefix-dependencies": [
            "strauss"
        ],
        "build": [
            "@composer install --no-dev",
            "@prefix-dependencies",
            "@composer dump-autoload -o"
        ]
    },
    "extra": {
        "strauss": {
            "target_directory": "src/Vendor",
            "namespace_prefix": "AbozaidBookingEngineVendor",
            "classmap_prefix": "Abozaid_BookingEngine_Vendor_",
            "constant_prefix": "ABOZAID_BOOKING_VENDOR_"
        }
    }
}

الخطوة 2: تشغيل أمر العزل التلقائي

في التيرمينال، بتنفذ الأمر ده:

composer run prefix-dependencies

أداة Strauss هتقرأ كل الحزم الموجودة في vendor/، وتنسخها داخل مجلد src/Vendor/ مع تعديل فضاءات الأسماء لتصبح:

AbozaidBookingEngineVendorFirebaseJWTJWT

وتولد محمل فئات خاص بيهم متوافق مع PSR-4 تماماً.

الخطوة 3: استدعاء الحزم المعزولة في كود إضافتك بنظافة

تعال شوف إزاي بتستدعي المكتبة المعزولة في كودك بدون أي خوف:

 'https://example.com',
            'sub' => $userId,
            'iat' => time(),
            'exp' => time() + $expiration
        ];

        // استدعاء الكلاس المعزول في أمان تام
        return JWT::encode($payload, $this->secretKey, 'HS256');
    }

    public function validateToken(string $token): ?object {
        try {
            return JWT::decode($token, new Key($this->secretKey, 'HS256'));
        } catch (Exception $e) {
            error_log('JWT Validation Error: ' . $e->getMessage());
            return null;
        }
    }
}

تقنية PHP-Scoper في المشاريع الحساسة والمعقدة

لو مشروعك بيعتمد على مكتبات ضخمة جداً تحتوي على استدعاءات ديناميكية وثوابت متعددة (زي AWS SDK أو Symfony Components)، فأداة PHP-Scoper هي الخيار الأكثر عمقاً وقوة في العالم.

ميزة PHP-Scoper هي ملف الإعداد scoper.inc.php اللي بيسمح لك بعمل Whitelist للكلاسات والدوال العامة لووردبريس، عشان تضمن إن الأداة متلعبش في كلاسات ووردبريس الأساسية زي WP_Error أو wpdb أو دوال get_option():

 'AbozaidBookingEngineVendor',

    // الكلاسات المستثناة من إعادة التسمية (كلاسات ووردبريس والنواة)
    'exclude-classes' => [
        'WP_Error',
        'WP_User',
        'WP_Query',
        'wpdb',
        'DateTime',
        'Exception',
        'stdClass'
    ],

    // الدوال المستثناة
    'exclude-functions' => [
        'get_option',
        'update_option',
        'wp_mail',
        'add_action',
        'add_filter'
    ],
];

دراسة حالة حقيقية: كارثة منصة حجز الغطس بالغردقة

عشان تعرف حجم الخسائر المالية اللي بيسببها إهمال عزل التبعيات، هشاركك واقعة حقيقية حصلت مع منصة حجز رحلات بحرية وفنادق في مدينة الغردقة على البحر الأحمر بتستقبل حجوزات سياح أجانب من ألمانيا وإنجلترا:

الكارثة:
المنصة كانت شغالة بإضافة حجز متطورة بتخزن صور جوازات السفر وتأكيدات الحجز على سحابة أمازون AWS S3 باستخدام مكتبة aws/aws-sdk-php المثبتة عبر Composer بنسخة بتعتمد على guzzlehttp/guzzle: ^7.2.

في منتصف شهر يوليو (موسم الذروة السياحية)، مدير الموقع قرر يركب إضافة نسخ احتياطي سحابي مجانية من متجر ووردبريس اسمها UpdraftPlus أو شبيهة بيها عشان يعمل Backup دوري للموقع.
المصيبة إن إضافة النسخ الاحتياطي دي كانت مثبتة معها نسخة قديمة جداً من guzzlehttp/guzzle: 5.3 وكانت بتتحمل الأول مع بداية تشغيل إضافات ووردبريس!

لحظة الانهيار:
السياح لما كانوا ييجوا يدفعوا بالفيزا ويحجزوا رحلات الغطس، إضافة الحجز كانت بتنادي على دوال التخزين السحابي اللي بتعتمد على Guzzle 7 الحديث. وبما إن Guzzle 5 هو اللي متحمل في الذاكرة، النظام كان بيرمي Fatal Error:

Fatal error: Call to undefined method GuzzleHttpClient::sendAsync()!

شاشات الدفع علقت، والسياح فلوسهم اتخصمت من بنوكهم لكن الحجوزات متسجلتش على السيستم، والمنصة خسرت في خلال 36 ساعة أكتر من 42,000 يورو في حجوزات ملغية وتعويضات وسمعة سيئة جداً على منصات التقييم العالمية (Tripadvisor).

الحل المعماري الجذري:
لما استلمت المشكلة:

1. عزل مكتبات AWS SDK و Guzzle بالكامل: تم تطبيق أداة Strauss على إضافة الحجز، وتمت إعادة كتابة كل كلاسات Guzzle و AWS لتعيش داخل AbozaidScubaVendorGuzzleHttp....
2. بناء خط إنتاج آلي (Automated Build Pipeline): تم إعداد GitHub Actions بحيث يقوم آلياً بتشغيل Strauss وتوليد حزمة الـ ZIP الخاصة بالإضافة وهي معزولة تماماً قبل النشر على السيرفر.
3. الاختبار والعودة للحياة: عادت المنصة للعمل بكفاءة 100%، وتم اختبار تشغيل 5 إضافات مختلفة كلها تستخدم نسخاً متضاربة من Guzzle في نفس الصفحة، وعملت جميعها بانسجام وسلام تام بدون أي تضارب!

الوصايا العشر لإدارة تبعيات Composer في ووردبريس

1. إياك وتوزيع vendor عادي في إضافتك: لا ترفع مجلد vendor/ بدون عزل فضاءات أسمائه إذا كانت إضافتك ستعمل في مواقع عامة.
2. اعتمد أداة عزل معتمدة (Scoper or Strauss): اختر الأداة التي تناسب حجم مشروعك واجعلها خطوة أساسية في عملية الـ Build.
3. استثنِ كلاسات ووردبريس من العزل (Whitelist WordPress): تأكد أن أداة العزل لا تعدل أسماء كلاسات النظام الأساسية مثل WP_Error و $wpdb.
4. ثبت ملف composer.lock في Git: احتفظ بملف composer.lock في مستودع مشروعك لضمان أن كل أعضاء الفريق يعملون على نفس النسخ الدقيقة للمكتبات.
5. استخدم –no-dev في حزم الإنتاج: لا ترفع مكتبات الاختبار والتطوير مثل PHPUnit أو Mockery إلى سيرفرات العملاء لتقليل حجم الإضافة.
6. افحص التراخيص البرمجية (Licenses): تأكد أن المكتبات التي تضيفها عبر Composer متوافقة مع ترخيص GPL v2/v3 المعتمد في ووردبريس.
7. احذر من التبعيات التراكمية (Transitive Dependencies): راقب شجرة التبعيات وتجنب تثبيت مكتبات ضخمة من أجل دالة واحدة يمكنك كتابتها بنفسك.
8. فعل Classmap Optimization: شغل composer dump-autoload -o بعد الانتهاء من عملية العزل لضمان أقصى سرعة تحميل ممكنة.
9. أتمت عملية البناء (CI/CD Automation): اجعل عزل التبعيات خطوة آلية تنفذ عند عمل Release جديد لتجنب الأخطاء البشرية.
10. اختبر إضافتك بجوار إضافات السوق الشهيرة: اختبر إضافتك دائماً بجوار إضافات مثل WooCommerce و Yoast و WP Rocket للتأكد من عدم وجود أي تعارض في التبعيات المشتركة.

أتمتة بناء الحزم المعزولة عبر خطوط الإنتاج (GitHub Actions CI/CD)

من أكبر الأخطاء التي يقع فيها المطورون المبتدئون هو الالتزام برفع مجلد الحزم المعزولة src/Vendor/ مباشرة إلى مستودع Git الخاص بالمشروع! رفع الحزم المعزولة في Git يلوث سجل التعديلات (Git History)، ويزيد من حجم المستودع بشكل هائل، ويصعب مراجعة التعديلات البرمجية (Code Review).

الحل الاحترافي الذي تطبقه كبرى الشركات البرمجية هو ترك مستودع Git نظيفاً يحتوي فقط على الكود المصدري الأصلي وملف composer.json، وتوكيل مهمة العزل والبناء لخط إنتاج سحابي مؤتمت بالكامل عبر GitHub Actions.

تعال نشوف ملف العمل .github/workflows/release.yml الجاهز للإنتاج:

name: Build & Release Scoped WordPress Plugin

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Setup PHP Environment
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          tools: composer:v2

      - name: Install Development Dependencies & Scoper
        run: composer install --prefer-dist --no-interaction

      - name: Run Namespace Prefixing (Strauss / Scoper)
        run: composer run prefix-dependencies

      - name: Clean Dev Dependencies & Optimize Classmap
        run: |
          composer install --no-dev --prefer-dist --no-interaction
          composer dump-autoload -o --no-dev

      - name: Create Production ZIP Archive
        run: |
          zip -r my-enterprise-plugin.zip . -x "*.git*" "*.github*" "tests/*" "node_modules/*"

      - name: Publish GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: my-enterprise-plugin.zip
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

بهذا الإعداد الرائع، بمجرد أن تضع Tag جديد للإصدار في Git (مثل git tag v2.1.0 && git push --tags)، يقوم السيرفر السحابي بتثبيت التبعيات، وتشغيل العزل، وتوليد ملف ZIP جاهز ونظيف تماماً للعملاء ومرفوع في صفحة الإصدارات في أقل من دقيقة واحدة!

معضلة الـ Polyfills والدوال العامة: كيف تتعامل مع حزم Symfony و PHP Core؟

أحياناً تجد نفسك مضطراً لتثبيت مكتبات تستخدم حزم “الترقيع المستقبلي” المعروفة بـ Polyfills، مثل symfony/polyfill-php80 أو symfony/polyfill-mbstring، والتي توفر دوال PHP الحديثة على السيرفرات القديمة (مثل str_contains() أو str_starts_with()).

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

عشان كده، في ملف إعداد scoper.inc.php أو إعدادات Strauss المتقدمة، يجب استثناء دوال الـ Polyfills من العزل صراحة:

 [
        'str_contains',
        'str_starts_with',
        'str_ends_with',
        'fdiv',
        'get_debug_type',
        'preg_last_error_msg'
    ],
];

المستودعات الخاصة بالوكالات البرمجية (Private Composer Packages)

لو أنت شغال في وكالة برمجية أو شركة برمجيات بتطور عشرات المواقع للعملاء، مش هتعيد كتابة كود الربط مع بوابات الدفع المصرية (Fawry, Paymob, Aman) في كل موقع من الصفر!

الحل هو إنشاء حزم خاصة داخلية للشركة (Private Packages) على GitHub أو GitLab، واستدعاؤها داخل ملف composer.json الخاص بإضافات العملاء باستخدام نوع المستودع vcs:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:my-agency/egyptian-payment-gateways.git"
        }
    ],
    "require": {
        "my-agency/egyptian-payment-gateways": "^1.5"
    }
}

ثم تطبيق تقنية العزل (Scoping) في الإضافة النهائية، مما يمنح شركتك سرعة خيالية في تطوير المواقع مع ضمان أمان كامل للمكتبات وعزلها التام في مواقع العملاء.

تخسيس مجلد التبعيات (Vendor Slimming) للاستضافات المشتركة

لو أنت بتبني إضافة مخصصة لجمهور عريض في مصر والوطن العربي، لازم تضع في اعتبارك أن شريحة كبيرة من عملائك بيستخدموا استضافات مشتركة محدودة الموارد (Shared Hosting) بمساحات تخزين صغيرة وحدود ذاكرة (Memory Limits) تتراوح بين 128 إلى 256 ميجابايت.

تضمين حزم Composer كاملة بدون تنظيف بينزل معاه مئات الملفات الزائدة التي لا وظيفة لها في بيئة الإنتاج؛ زي ملفات README.md، ومجلدات الاختبارات tests/، وملفات التوثيق docs/، وقوالب GitHub!

عشان تخفف حجم إضافتك بنسبة تصل لأكثر من 60%، الممارسة الهندسية الفضلى هي كتابة سكربت تنظيف بسيط في composer.json يتم تنفيذه بعد تثبيت الحزم وقبل عملية العزل:

# أمر تنظيف سريع لحذف ملفات الاختبار والتوثيق من مجلد vendor
find vendor/ -type d -name "tests" -exec rm -rf {} +
find vendor/ -type d -name "test" -exec rm -rf {} +
find vendor/ -type d -name "docs" -exec rm -rf {} +
find vendor/ -type f -name "*.md" -delete
find vendor/ -type f -name ".gitignore" -delete

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

استكشاف وحل مشكلات التبعيات الديناميكية المعزولة (Troubleshooting)

في بعض الأحيان، قد تواجه مكتبة خارجية تعتمد على استدعاء الكلاسات بطريقة ديناميكية بحتة مثل:

$driver = 'GuzzleHttpClient'; new $driver();

أدوات العزل مثل PHP-Scoper و Strauss تفحص الكود عبر تحليل الشجرة النحوية (AST – Abstract Syntax Tree)، وقد لا تتمكن من اكتشاف أسماء الكلاسات المخزنة كسلاسل نصية مجردة (Hardcoded Strings).

إذا ظهر لك خطأ بعد العزل يفيد بعدم العثور على كلاس معين (Class Not Found)، فالحل هو فحص ملفات المكتبة وتحديد النصوص الديناميكية، وإضافتها في قسم الاستبدال الصريح (Custom Regex / Patching) داخل إعدادات الأداة ليتم تعديلها بأمان قبل تجميع الحزمة، مما يضمن عمل أكثر المكتبات تعقيداً بنجاح تام واستقرار مطلق.

الفحص الأمني المستمر للتبعيات عبر composer audit

لا تنسَ أبداً تضمين خطوة composer audit في خطوط الإنتاج والـ CI/CD الخاصة بمشروعك. هذه الأداة تفحص التبعيات الخارجية للتأكد من خلوها من أي ثغرات أمنية مكتشفة حديثاً، وتحميك من تضمين مكتبات تحتوي على ثغرات حقن أو تجاوز الصلاحيات قبل شحن النسخة للعملاء.