PHP Composer: установка пакетов и автозагрузка классов

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 восстанавливает её по lock-файлу.

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 напрямую.