كيفية استخدام Composer المدمج في ServBay لإدارة مشاريع PHP

باعتباره بيئة تطوير ويب محلية قوية، يأتي ServBay مُثبتًا مسبقًا مع Composer، مما يُبسط إلى حد كبير إدارة تبعيات مشاريع PHP. يُعد Composer أداة لا غنى عنها في تطوير PHP الحديث، حيث يساعد المطورين على دمج وإدارة مكتبات الطرف الثالث بسهولة، التعامل مع التبعيات المعقدة تلقائيًا، ويوفر مزايا التحميل التلقائي المريحة. مع ServBay، يمكنك استخدام Composer مباشرةً دون الحاجة لتثبيته أو إعداده بشكل منفصل، مما يُسرع سير عملك في تطوير PHP على الفور.

مقدمة عن Composer

Composer هي أداة تُستخدم لإدارة التبعيات في مشاريع PHP. تتيح للمطورين تعريف المكتبات الخارجية (التي تُسمى عادةً بالحزم) التي يعتمد عليها المشروع، وتوفر طريقة تلقائية لتثبيتها وتحديثها. لا يقتصر Composer على إدارة مكتبات PHP فحسب، بل يمكنه إدارة أنواع أخرى من الحزم مثل الأطر والمكونات والإضافات.

الميزات الرئيسية

1. إدارة التبعيات: يقوم Composer بإدارة تبعيات المشروع تلقائيًا، مع ضمان توافق إصدارات جميع المكتبات المطلوبة وحل مشاكل التضارب المحتملة.
2. التحميل التلقائي: يُقدّم Composer وظيفة التحميل التلقائي بفضل توليد ملف تحميل مركزي، بحيث يمكنك استخدام الكلاسات المُثبتة عبر Composer دون كتابة include أو require يدويًا.
3. التحكم في الإصدارات: يمكنك تحديد شروط الإصدارات للمكتبات في ملف composer.json، وسيقوم Composer بتحميل الإصدارات المتوافقة وتثبيتها، كما يقوم بقفل الإصدارات الدقيقة في ملف composer.lock. ذلك يضمن توحيد الإصدار بين أعضاء الفريق ومختلف البيئات.
4. إدارة الحزم: يعتمد Composer بشكل رئيسي على مستودع Packagist المركزي للعثور على الحزم وتحميلها، ما يتيح للمطورين إيجاد ودمج أشهر مكتبات PHP بسهولة.
5. دعم المجتمع: يحظى Composer بمجتمع مطورين نشط جدًا وموارد توثيقية غنية.

Composer المدمج داخل ServBay

يُوفر ServBay إصدارات متعددة من PHP، ويأتي Composer مثبتًا مسبقًا مع عملية التثبيت. هذا يعني أنك لست بحاجة لتحميل أو إعداد Composer يدوياً. يضمن ServBay توفر Composer في بيئة النظام، وغالبًا ما يرتبط بالإصدار النشط من PHP في لوحة تحكم ServBay، بحيث يمكنك ببساطة استعمال أوامر composer أو composer-2.2 في الطرفية الخاصة بالمشروع.

تنبيه

يتوفر Composer بإصدارين مختلفين: الإصدار الأحدث Composer 2.8.x، وإصدار متوافق مع إصدارات PHP القديمة Composer 2.2.x LTS، حيث يدعم كل منهما:

• PHP 7.2+ مع Composer 2.8.x
• PHP 5.3 - PHP 7.1 مع Composer 2.2.x LTS

يأتي ServBay افتراضياً مع Composer 2.8.x المناسب لـ PHP 7.2 وأعلى.

إذا كنت بحاجة لاستخدام PHP 5.3 حتى 7.1، يمكنك تثبيت Composer 2.2.x LTS من ضمن "الحزم البرمجية" بواجهة ServBay، ثم استخدام الأمر composer-2.2 بعد إكمال التثبيت. علماً أن كلا الإصدارين لا يتعارضان مع بعضهما.

إدارة تبعيات المشروع باستخدام Composer

يتم إدارة التبعيات في Composer من خلال ملف composer.json الموجود في جذر مشروعك. إليك الخطوات الأساسية لإنشاء واستخدام هذا الملف:

1. إنشاء ملف composer.json

في مجلد مشروع PHP الخاص بك، أنشئ ملفًا باسم composer.json. على سبيل المثال، إذا كنت تعمل في مجلد /Applications/ServBay/www/my_php_project، أنشئ الملف هناك.

يحتوي الملف على كائن JSON حيث يُحدد المفتاح require تبعيات المشروع. كل مفتاح هو اسم الحزمة (عادةً بالصيغة vendor/package) والقيمة هي شرط الإصدار المطلوب.

مثال لتثبيت مكتبة Monolog (وهي مكتبة تسجيل شهيرة للـ PHP)، بإصدار 2.0 على الأقل:

{
    "require": {
        "monolog/monolog": "^2.0"
    }
}

يشير الرمز ^2.0 إلى تثبيت أي إصدار متوافق مع 2.0.0 وما فوق حتى أقل من 3.0.0.

2. تثبيت المكتبات المطلوبة

من جذر المشروع الذي يحتوي على composer.json، افتح الطرفية ونفذ الأمر التالي:

composer install

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

• سيقرأ Composer ملف composer.json.
• سيحسب كل التبعيات المطلوبة (من ضمنها المكتبات الثانوية).
• سيقوم بتحميلها داخل مجلد vendor داخل المشروع.
• سيتم توليد ملف composer.lock الذي يسجّل بدقة إصدارات جميع المكتبات المثبتة حاليًا. يعتبر ملف composer.lock مهمًا جداً وينبغي رفعه إلى نظام التحكم في الإصدارات مثل Git لضمان تطابق بيئة التعاون والنشر.
• سيُنشئ ملف التحميل التلقائي vendor/autoload.php.

عند اكتمال التثبيت ستلاحظ وجود مجلد vendor وملف composer.lock في مجلد مشروعك.

استخدام خاصية التحميل التلقائي في Composer

واحدة من أهم مميزات Composer هي دعم التحميل التلقائي للكلاسات طبقًا للمعايير (PSR-0, PSR-4)، وهو ما يسهّل تنظيم التعليمات البرمجية.

إليك كيف يمكنك إعداد واستخدام التحميل التلقائي:

1. تهيئة حقل autoload

أضف أو عدّل الحقل autoload في ملف composer.json، مثلاً لتعيين المعيار PSR-4 وربط مساحة الأسماء App\ بمجلد src/ في جذر المشروع:

{
    "require": {
        "monolog/monolog": "^2.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

هذا يعني أن أي كلاس يندرج تحته namespace يبدأ بـ App\ سيبحث Composer عن ملفه المناظر في مجلد src/.

2. توليد ملفات التحميل التلقائي

عند أي تغيير في إعدادات autoload، تحتاج لتحديث الخريطة عبر الأمر:

composer dump-autoload

هذا الأمر سيعيد إنشاء ملف vendor/autoload.php. إذا كنت مجرد تثبت/حدثت تبعيات بدون تغيير الضبط، سيُجري هذا الإجراء تلقائيًا عند تنفيذ composer install أو composer update.

3. إدراج ملف التحميل التلقائي في الشيفرة

في بداية سكريبت PHP الخاص بك أضف:

<?php

// إدراج ملف التحميل التلقائي الخاص بـ Composer
require __DIR__ . '/vendor/autoload.php';

// يمكنك الآن استخدام أي كلاس مثبت عبر Composer أو قمت بتعريف namespace له في autoload
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use App\MyClass; // إذا ضبطت التحميل التلقائي لـ namespace App\

// استخدام مكتبة Monolog
$log = new Logger('name');
$log->pushHandler(new StreamHandler('your.log', Logger::WARNING));
$log->warning('هذه رسالة تحذير!');

// استخدام كلاس خاص بك (إذا ضبطت autoload)
// $myObject = new MyClass();
// $myObject->doSomething();

?>

عن طريق السطر require __DIR__ . '/vendor/autoload.php'; أصبحت جميع الكلاسات المدارة عبر Composer متاحة في مشروعك دون كتابة require أو include لكل واحدة من المكتبات، ما يُبسط التعليمات البرمجية كثيرًا.

تحديث المكتبات

مع تطور المشروع وتحديث المكتبات، قد ترغب بتحديث الإصدارات الموجودة.

من جذر المشروع، نفذ الأمر التالي:

composer update

• سيقوم Composer بفحص القيود في composer.json بحثًا عن أحدث الإصدارات المتاحة التي توافق الشروط.
• في حال توفر تحديثات، سيُنزِلها ويحدّث المكتبات.
• يُحدّث أيضًا ملف composer.lock ليعكس التغييرات الجديدة.

ملاحظة مهمة:

• composer install مقابل composer update: يُستخدم composer install عند تثبيت التبعيات لأول مرة أو إعادة نشر مشروع في بيئة جديدة، حيث يعتمد كليًا على ملف composer.lock ليثبّت نفس الإصدارات بدقة. أما composer update فيُستخدم لتحديث المكتبات بما يتوافق مع شروط composer.json ويُحدث كذلك ملف composer.lock. في فرق العمل، ينصح باستخدام composer update فقط عند الحاجة الفعلية وتحديث الملفات في نظام التحكم بالنسخ بعد التحديث.

ملاحظات عند استخدام Composer داخل ServBay

يقدم ServBay تجربة سهلة لتطوير PHP محلياً، لكن هناك بعض النقاط التي يجب مراعاتها عند استخدام Composer:

1. بيئة الطرفية: احرص على تشغيل أوامر Composer في طرفية ServBay (Terminal). يقوم ServBay عادة بإضافة إصدار PHP النشط إلى متغير البيئة PATH على النظام، وبذلك يصبح بإمكانك تشغيل أوامر php وcomposer تلقائياً في الطرفيات الجديدة. إذا واجهت خطأ مثل command not found، أعد فتح الطرفية أو تحقق من أن ServBay يعمل بشكل طبيعي.
2. إصدار PHP: يتيح لك ServBay التبديل بسهولة بين عدة إصدارات PHP. تؤدي أوامر composer باستخدام إصدار PHP النشط حالياً. للprojects التي تتطلب إصدارات معينة من PHP، قم أولاً بتحديد الإصدار المطلوب في لوحة تحكم ServBay ثم نفّذ أوامر Composer.
3. مسار المشروع: يُنصح بوضع المشاريع داخل المسار الافتراضي لمواقع ServBay /Applications/ServBay/www، داخل مجلد فرعي، وضبط إعدادات الموقع عبر لوحة التحكم للوصول إليها عبر المتصفح. نفّذ دائماً أوامر Composer داخل مجلد المشروع المناسب.

مشروع توضيحي: استخدام مكتبة GuzzleHttp

فيما يلي مثال عملي يوضح كيفية تثبيت واستخدام مكتبة GuzzleHttp (واحدة من أشهر عملاء HTTP لـ PHP) في بيئة ServBay:

1. إنشاء مجلد المشروع والدخول إليه: من جذر مواقع ServBay، أنشئ مجلدًا جديدًا وادخل إليه عبر الطرفية:

   cd /Applications/ServBay/www
   mkdir guzzle_demo.servbay.demo
   cd guzzle_demo.servbay.demo

   اخترنا اسم المجلد ليطابق نظام تسمية مواقع العرض لـ ServBay.

2. إنشاء ملف composer.json: في نفس المجلد، أنشئ ملف composer.json بالمحتوى التالي:

   {
       "require": {
           "guzzlehttp/guzzle": "^7.0"
       },
       "autoload": {
            "psr-4": {
                "App\\": "src/"
            }
        }
   }

   تم تضمين إعداد التحميل التلقائي PSR-4 كخطوة احترافية جيدة حتى إن لم نستخدمه الآن.

3. تثبيت التبعيات: من نفس المجلد، نفذ الأمر:

   composer install

   سيقوم Composer بتنزيل GuzzleHttp وجميع تبعياته، وإعداد مجلد vendor وملف composer.lock.

4. كتابة ملف PHP للاستفادة من المكتبة: أنشئ ملفًا باسم index.php بنفس المجلد:

   <?php
   // إدراج ملف التحميل التلقائي الخاص بـ Composer
   require __DIR__ . '/vendor/autoload.php';
   
   use GuzzleHttp\Client;
   use GuzzleHttp\Exception\RequestException;
   
   echo "<h1>عرض GuzzleHttp</h1>";
   echo "<pre>";
   
   try {
       // إنشاء نموذج عميل Guzzle
       $client = new Client();
   
       // تنفيذ طلب GET
       $response = $client->request('GET', 'https://httpbin.org/get', [
           'query' => ['param1' => 'value1', 'param2' => 'value2']
       ]);
   
       // عرض محتوى الاستجابة
       $body = $response->getBody()->getContents();
       echo "محتوى الاستجابة:\n";
       echo $body;
   
       // عرض كود الحالة
       $statusCode = $response->getStatusCode();
       echo "\n\nكود الحالة: " . $statusCode;
   
   } catch (RequestException $e) {
       // معالجة استثناءات الطلبات
       echo "حدث استثناء في الطلب:\n";
       echo $e->getMessage();
       if ($e->hasResponse()) {
           echo "\nحالة الاستجابة: " . $e->getResponse()->getStatusCode();
           echo "\nمحتوى الاستجابة: " . $e->getResponse()->getBody()->getContents();
       }
   } catch (\Exception $e) {
       // معالجة استثناءات أخرى
       echo "حدث خطأ:\n";
       echo $e->getMessage();
   }
   
   echo "</pre>";
   ?>

   هذا الملف يشمل التحميل التلقائي، ثم ينفذ طلب HTTP لاختبار API ويعرض النتائج.

5. إعداد الموقع في ServBay: افتح لوحة تحكم ServBay، ثم انتقل إلى تبويب "المواقع" (أو "Sites") وأضف موقعًا جديدًا يشير إلى المسار /Applications/ServBay/www/guzzle_demo.servbay.demo واضبط اسم النطاق ليكون guzzle_demo.servbay.demo. احفظ الإعدادات وأعد تشغيل خادم الويب (مثل Caddy أو Nginx) إذا لزم الأمر.

6. زيارة المشروع عبر المتصفح: توجه في المتصفح إلى العنوان http://guzzle_demo.servbay.demo/، يجب أن ترى نتيجة تنفيذ سكريبت PHP تعرض البيانات المسترجعة من https://httpbin.org/get.

الأسئلة الشائعة (FAQ)

س: أستخدم PHP 5.6 ولا يعمل Composer بشكل صحيح، ماذا أفعل؟

ج: يوفر ServBay إصدارين من Composer: 2.8.x الحديث و2.2.x LTS المتوافق مع PHP القديم. لدعم PHP 5.6 عليك تثبيت Composer 2.2 LTS واستخدام الأمر composer-2.2.

س: عند تنفيذ أمر composer في الطرفية تظهر رسالة command not found، ما الحل؟

ج:

1. تأكد أن تطبيق ServBay يعمل.
2. أغلق وأعد فتح نافذة الطرفية. عند تشغيل ServBay يتم إعداد متغيرات البيئة للطرفيات الجديدة.
3. تحقق من تنشيط إصدار PHP واحد على الأقل من خلال لوحة تحكم ServBay.
4. إذا استمرت المشكلة، يمكنك محاولة تنفيذ Composer عبر مسار PHP في ServBay، مثلاً /Applications/ServBay/php/8.2/bin/php /usr/local/bin/composer install (قد تحتاج لتعديل المسارات حسب إصدار PHP وComposer المثبت، لكن الغاية أن ServBay مصمم ليسمح لك باستخدام أمر composer بشكل مباشر).

س: كيف أُحدد أي إصدار PHP يستخدمه Composer داخل ServBay؟

ج: بشكل افتراضي سيستخدم Composer الإصدار النشط حاليًا في لوحة تحكم ServBay. يمكنك اختيار إصدار PHP المطلوب من التبويب المناسب وتفعيله، ثم فتح طرفية جديدة وتنفيذ أوامر Composer وسيتم الاعتماد على ذلك الإصدار.

س: ما هي أهمية ملف composer.lock؟ وهل يجب رفعه إلى Git؟

ج: ملف composer.lock يُسجل بدقة إصدارات جميع التبعيات التي ثبتها آخر مرة. ينصح بشدة رفع الملف إلى نظام التحكم بالنسخ (Git مثلا). بهذا الشكل تضمَن توحيد تثبيت التبعيات وحلول جميع أعضاء الفريق، بيئات الاختبار والإنتاج، على نفس الإصدارات بالضبط، مما يمنع مشاكل “يعمل عندي فقط” ويحد من مشاكل الاستقرار أثناء النشر. عند استنساخ مشروع جديد وتنفيذ أمر composer install سيتم أخذ الإصدارات تلقائيًا من composer.lock.

ملخص

يتيح لك ServBay بدمجه مع Composer بيئة تطوير PHP محلية شاملة وفعّالة. يمكنك بسهولة إدارة التبعيات والعمل مع التحميل التلقائي بمختلف إصدارات PHP، ما يسمح لك بالتركيز على كتابة الكود ورفع جودة وكفاءة مشاريعك. الجمع بين ServBay وComposer هو الخيار الأمثل لتطوير PHP عصري وسريع وسلس.