كنا في السابق، لاستخدام مكتبة، نحمّل ملفها ونضعه في مجلد وننادي عليه بـrequire. فكانت النتيجة نسخًا قديمة منسية لا يعرف أحد أين هي. ينظّم Composer هذا العمل: تحدد الحزم التي تحتاجها والنسخ المقبولة، وهو يتولى الباقي.

لارافيل مبني بالكامل على Composer، وحتى في ووردبريس تُثبَّت به معظم الأدوات الاحترافية. لذلك فإن تعلّمه من أولى الاستثمارات لمبرمج PHP.

ماذا يفعل Composer بالضبط#

Composer هو مدير حزم PHP، وله ثلاث مهام رئيسية:

  1. ينزّل الحزم المطلوبة واعتمادياتها من المستودع العام Packagist.
  2. يجد النسخ المتوافقة ويسجلها بدقة.
  3. يبني محمّلًا تلقائيًا (autoloader) لتُحمَّل الفئات دون require يدوي.

ثبّته من الدليل الرسمي getcomposer.org لأن طريقة التثبيت تختلف حسب نظام التشغيل. وبعد التثبيت يجب أن يستجيب الأمر composer --version.

بدء مشروع وتثبيت حزمة#

نفّذ هذا في مجلد المشروع:

Bash
composer init
composer require monolog/monolog

ينشئ الأمر الأول ملف composer.json، ويثبّت الثاني الحزمة. بعدها يظهر ثلاثة أشياء: composer.json وcomposer.lock ومجلد vendor. استخدام بسيط:

PHP
<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log'));
$log->warning('سجّل المستخدم دخوله');

يكفي require واحد لـautoload؛ وبقية الفئات تُكتشف تلقائيًا.

composer.json وcomposer.lock#

تكتب أنت ملف composer.json وهو يقول ما تريده:

JSON
{
    "name": "acme/shop",
    "require": {
        "php": "^8.1",
        "monolog/monolog": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

تعني ^3.0 أي نسخة متوافقة مع 3 دون تغيير غير متوافق. أما ملف composer.lock فيكتبه Composer نفسه ويسجل فيه النسخة الدقيقة لكل حزمة. والقاعدة الذهبية:

الملفمن يكتبههل يوضع في Git؟
composer.jsonأنتنعم
composer.lockComposerنعم (للتطبيقات)
vendor/Composerعادةً لا

يضمن lock أن يشغّل الخادم وجهازك النسخة نفسها تمامًا. ولإدارة هذه الملفات في Git راجع Git للمبتدئين.

autoload بمعيار PSR-4#

يقول قسم autoload في المثال أعلاه إن فئات مساحة الاسم (namespace) المسماة App موجودة في مجلد src. أي أن الفئة App\Service\Mailer يجب أن تكون في src/Service/Mailer.php:

PHP
<?php
declare(strict_types=1);

namespace App\Service;

final class Mailer
{
    public function send(string $to, string $subject): bool
    {
        // منطق الإرسال
        return true;
    }
}

بعد تعديل قسم autoload نفّذ composer dump-autoload ليُعاد بناء الخريطة. ويجب أن يطابق اسم الملف اسم الفئة بالحالة نفسها للأحرف الكبيرة والصغيرة، لأن خادم لينكس حساس لها.

الأوامر اليومية#

  • composer install: يثبّت النسخ المسجلة في lock. على الخادم ولزملاء الفريق.
  • composer update: يحدّث الحزم وفق القيود ويغيّر lock. على جهاز التطوير.
  • composer require vendor/pkg: يضيف حزمة جديدة.
  • composer remove vendor/pkg: يحذف حزمة.
  • composer outdated: يعرض الحزم التي لها نسخة أحدث.
  • composer audit: يفحص الاعتماديات مقابل قائمة الثغرات الأمنية المعروفة.

شغّل composer audit بين حين وآخر؛ فالحزمة القديمة من أشهر منافذ دخول المهاجمين. وقد كتبنا عن بقية المنافذ في أمان كود PHP.

النشر على الاستضافة المشتركة#

على خادم الإنتاج لا تثبّت حزم التطوير، وحسّن المحمّل التلقائي:

Bash
composer install --no-dev --optimize-autoloader

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

لا تجعل مجلد vendor متاحًا مباشرةً من الويب أبدًا. الأفضل أن يكون خارج الجذر العام للموقع.

ملاحظات أمنية#

لا تثبّت حزمة مجهولة: انظر إلى اسم المستودع وعدد المستخدمين وتاريخ آخر تحديث. فتثبيت أي حزمة يعني تشغيل كود لم تكتبه بنفسك. وإذا شغّلت Composer بصلاحية root فستعمل هذه السكربتات نفسها بصلاحيات كاملة. كذلك لا تكتب كلمات المرور ومفاتيح API في composer.json.

عندما يتعطل شيء ما#

ثلاث مشكلات تراها أكثر من غيرها. الأولى رسالة «Class not found» وتعني غالبًا أن namespace لا يطابق مسار الملف أو أنك لم تشغّل composer dump-autoload بعد تغيير autoload. الثانية تعارض النسخ: حزمتان تطلبان نسختين غير متوافقتين من اعتمادية واحدة. يشرح الأمر composer why-not vendor/pkg 2.0 ما الذي منع التثبيت. والثالثة عدم توافق إصدار PHP؛ فقسم config.platform.php في composer.json يطلب من Composer حل النسخ وفق PHP الاستضافة لا PHP جهازك.

JSON
{
    "config": {
        "platform": { "php": "8.1.0" },
        "sort-packages": true
    }
}

كيف نميّز الحزمة الجيدة#

قبل composer require خصّص دقيقتين. انظر هل ما زال المستودع قيد الصيانة، وكم من المشكلات المفتوحة بلا رد، وكم حزمة أخرى تعتمد عليه، وهل ترخيصه يناسب مشروعك. والحزمة التي تجلب مئة اعتمادية لمهمة من عشرة أسطر لا تستحق ذلك عادةً. فكل اعتمادية جديدة تعني كودًا عليك إبقاؤه محدّثًا ومخاطرة عليك قبولها.

الخلاصة#

  • يدير Composer الحزم والنسخ وautoload.
  • composer.json هو طلبك، وcomposer.lock هو النسخة الدقيقة المثبّتة؛ احتفظ بكليهما في Git.
  • على الخادم نفّذ composer install وشغّل update على جهاز التطوير فقط.
  • autoload بمعيار PSR-4 يعني أن اسم الملف والمجلد وnamespace يجب أن تتطابق.
  • في الإنتاج استخدم --no-dev --optimize-autoloader.
  • شغّل composer audit بانتظام ولا تثبّت إلا حزمًا موثوقة.