Composer في PHP: تثبيت الحزم والتحميل التلقائي للأصناف

Composer هو مدير الحزم في PHP. شغّل composer require vendor/package في مجلد مشروعك: ينزّل Composer المكتبة إلى vendor/، ويسجلها في composer.json، وتحمّلها، مع كل ما ثبّته غيرها، بسطر واحد، require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

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

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

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

لا include لكل ملف: يحمّل المحمّل التلقائي Logger وStreamHandler وكل ما يستخدمانه أول مرة يُحتاج فيها إلى كل صنف. وتأتي الحزم من Packagist، السجل العام الذي يبحث فيه Composer افتراضيًا.

تثبيت Composer

يحتاج Composer إلى PHP على جهازك أولًا (راجع تثبيت PHP).

Windows: نزّل Composer-Setup.exe من getcomposer.org وشغّله. يجد ملف php.exe الخاص بك ويضيف composer إلى PATH. افتح طرفية جديدة بعد ذلك.

macOS مع Homebrew:

brew install composer

Linux: تعمل حزمة توزيعتك (sudo apt install composer على Debian وUbuntu) لكنها كثيرًا ما تكون إصدارًا أقدم. ويعطي المثبّت الرسمي الإصدار الحالي:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

تعرض صفحة التنزيل في getcomposer.org أيضًا سطرًا يتحقق من تجزئة المثبّت قبل تشغيله؛ انسخ الأوامر من هناك لتحصل على التجزئة الحالية. ثم تحقق من أنه يعمل:

composer --version

composer.json وcomposer.lock

يطرح composer init بضعة أسئلة ويكتب composer.json، أو ينشئه composer require مع أول حزمة. وهذا ملف نموذجي:

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• يسرد require ما يحتاجه المشروع ليعمل، بما فيه إصدار PHP.
• يسرد require-dev أدوات التطوير فقط (الاختبارات، والتحليل الساكن). يضيف إليه composer require --dev phpunit/phpunit، ويتخطاه composer install --no-dev على خوادم الإنتاج.
• يخبر autoload الأداة Composer أين تعيش أصنافك (أدناه).

وبجانبه، يكتب Composer الملف composer.lock بالإصدار الدقيق لكل حزمة ثبّتها، بما في ذلك الحزم التي تعتمد عليها حزمك. ارفع الملفين كليهما. ولا ترفع vendor/: أضفه إلى .gitignore، لأن composer install يعيد بناءه من ملف القفل.

composer install مقابل composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

شغّل composer install بعد استنساخ مشروع وفي كل عملية نشر: يحصل الجميع على الإصدارات نفسها التي اختُبرت. ولا تشغّل composer update إلا حين تنوي الترقية، ثم اختبر وارفع composer.lock الجديد. وتشغيل update على خادم إنتاج يثبّت إصدارات لم يختبرها أحد.

قيود الإصدارات: ^ و~

يختار composer require vendor/package دون إصدار أحدث إصدار مستقر ويكتب له قيد ^، وهذا عادة ما تريده.

التحميل التلقائي لأصنافك بـ PSR-4

PSR-4 هو الاصطلاح الذي يربط فضاء أسماء بمجلد: مع "App\\": "src/"، يعيش الصنف App\Text\Slug في src/Text/Slug.php. وبعد إضافة قسم autoload، شغّل:

composer dump-autoload

المحمّل التلقائي في Composer دالة مسجلة بـ spl_autoload_register()، تستدعيها PHP كلما استخدمت الشيفرة صنفًا لم يُحمَّل بعد. تكتب هذه الكتلة ملفي صنفين وتسجّل محمّلًا تلقائيًا صغيرًا خاصًا بها بأسلوب PSR-4، لتشاهد الربط وهو يعمل. أضف ملف صنف ثالثًا واستخدمه.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

يعمل المحمّل التلقائي مرة واحدة لكل صنف: لا يطبع استدعاء Slug::from() الثاني أي سطر autoload:، لأن الصنف محمّل أصلًا. وفي مشروع حقيقي لا تكتب هذه الدالة بنفسك أبدًا؛ يسجّل vendor/autoload.php نسخة Composer، التي تتعامل أيضًا مع الحزم في vendor/. وفضاءات الأسماء مشروحة في صفحة فضاءات الأسماء.

أخطاء شائعة

• Class "Monolog\Logger" not found. لم ينفّذ السكربت require 'vendor/autoload.php'، أو المسار خاطئ. استخدم __DIR__ . '/vendor/autoload.php' حتى لا يعتمد المسار على المجلد الحالي.
• صنفك لا يُعثر عليه بعد إضافته إلى autoload. شغّل composer dump-autoload، وتحقق من أن مسار الملف يطابق فضاء الأسماء تمامًا، بما في ذلك الأحرف الكبيرة والصغيرة: يجب أن يكون App\Text\Slug في src/Text/Slug.php، وتعامل خوادم Linux الملف src/text/slug.php على أنه ملف مختلف.
• Your requirements could not be resolved to an installable set of packages. حزمتان تحتاجان إلى إصدارين غير متوافقين من شيء ما، كثيرًا ما يكون PHP نفسها. تسرد الرسالة التعارض؛ ويشرح composer why-not vendor/package 2.0 ما يمنع إصدارًا.
• composer غير معروف. فُتحت الطرفية قبل التثبيت، أو المجلد ليس في PATH. افتح طرفية جديدة، أو استدعِ php composer.phar مباشرة.