Composer: установка и автозагрузка с нуля за 20 минут

К концу этой инструкции у вас будет установленный Composer, файл composer.json с одной зависимостью и автозагрузка классов, которая подтягивает и сторонние пакеты, и ваш собственный код без ручных require. На всё уйдёт минут двадцать, если PHP уже стоит. Проверено на Composer 2.x и PHP 8.1+.

Что нужно иметь до начала

• PHP версии 7.2.5 или выше. Проверьте командой php -v — Composer 2.x ниже 7.2.5 не запустится.
• Расширения PHP openssl, zip и curl включены. Без zip Composer будет качать пакеты медленнее через ручную распаковку, без openssl не соединится с репозиторием по HTTPS.
• Права на запись в каталог проекта — Composer создаёт папку vendor и файлы блокировок.
• Доступ в интернет к packagist.org — это основной репозиторий пакетов.

Проверить активные расширения можно так: php -m выведет список. Если zip или openssl в нём нет, включите их в вашем php.ini и перезапустите терминал.

Шаг 1. Установка Composer

Composer — это один PHP-файл composer.phar. Есть два пути: локальный (файл лежит в проекте) и глобальный (команда composer доступна отовсюду). Начнём с установки, а глобальный доступ настроим дальше.

Windows

Скачайте и запустите официальный установщик Composer-Setup.exe с сайта getcomposer.org. Он сам найдёт php.exe, пропишет путь в переменную окружения и проверит расширения. После установки закройте и снова откройте терминал.

Linux и macOS

Официальный скрипт установки проверяет контрольную сумму загрузчика. Актуальные четыре строки всегда лежат на странице загрузки getcomposer.org — не копируйте хеш из старых статей, он меняется с каждым релизом установщика. После скачивания перенесите файл в системный каталог:

# переносим phar в PATH и делаем исполняемым
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer

Проверка: выполните composer --version. Должна появиться строка вида Composer version 2.x.x. Если терминал отвечает «command not found» — файл не в PATH, вернитесь к шагу переноса.

Шаг 2. Инициализация проекта

Перейдите в пустую папку проекта и запустите мастер:

cd ~/projects/my-app
composer init

Мастер задаст вопросы: имя пакета в формате vendor/name (например, ivanov/my-app), описание, автор, лицензия. Про зависимости на этом этапе можно ответить «no» — добавим их следующим шагом. В конце появится готовый composer.json.

Проверка: в папке появился файл composer.json. Откройте его — внутри объект с полем name и тем, что вы ввели.

Шаг 3. Устанавливаем первый пакет

Возьмём популярный логгер Monolog — на нём удобно увидеть, как работает автозагрузка. Команда require и скачает пакет, и пропишет его в composer.json:

composer require monolog/monolog

Composer подберёт совместимую версию, создаст папку vendor и файл composer.lock с точными версиями всех зависимостей. В composer.json появится блок require.

Проверка: в проекте появились папка vendor, внутри неё vendor/monolog и vendor/autoload.php. Файл composer.lock лежит рядом с composer.json.

composer.lock — что это

composer.lock фиксирует точные версии всех установленных пакетов, включая зависимости зависимостей. При composer install на другой машине ставятся ровно те версии, что записаны в lock, — сборка воспроизводима. Файл коммитят в репозиторий для приложений и не коммитят для переиспользуемых библиотек.

Шаг 4. Подключаем автозагрузку

Весь смысл Composer — в файле vendor/autoload.php. Подключите его один раз в точке входа приложения, и дальше классы любых установленных пакетов доступны без единого require.

<?php
// index.php — точка входа приложения
require __DIR__ . '/vendor/autoload.php';

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

// класс Logger подгружен автозагрузчиком, ручного require нет
$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::WARNING));

$log->warning('Автозагрузка работает');
$log->error('И это тоже пишется в лог');

Проверка: запустите php index.php. Ошибок не будет, а рядом появится файл app.log с двумя строками. Если так — автозагрузка подключена.

Шаг 5. Автозагрузка вашего кода через PSR-4

Автозагрузка нужна не только для чужих пакетов. Опишите в composer.json, где лежат ваши классы, и Composer будет искать их так же автоматически. Добавьте секцию autoload:

{
    "name": "ivanov/my-app",
    "require": {
        "monolog/monolog": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Здесь префикс пространства имён App\ сопоставлен с папкой src/. Класс App\Service\Mailer Composer будет искать в файле src/Service/Mailer.php. После правки composer.json вручную обязательно пересоберите карту автозагрузки:

composer dump-autoload

Создайте файл src/Service/Mailer.php:

<?php
// src/Service/Mailer.php
namespace App\Service;

class Mailer
{
    public function send(string $to): string
    {
        return "Письмо для {$to} поставлено в очередь";
    }
}

Теперь класс доступен в index.php без require:

use App\Service\Mailer;

$mailer = new Mailer();
echo $mailer->send('client@example.com');

Проверка: php index.php выводит строку про очередь. Если видите Class "App\Service\Mailer" not found — вы забыли composer dump-autoload после правки autoload.

Правило PSR-4 простое: имя пространства имён после префикса точно повторяет путь к файлу от базовой папки, а имя класса совпадает с именем файла. Нарушили соответствие — автозагрузчик молча не найдёт класс.

Стандарты автозагрузки: чем отличаются

Если не получилось

• Your requirements could not be resolved to an installable set of packages — версия PHP не подходит под пакет или конфликт версий зависимостей. Запустите с ключом диагностики: composer require monolog/monolog -vvv, в выводе будет видно, какой пакет и какое ограничение мешает.
• Class "..." not found после добавления своего класса — не выполнили composer dump-autoload либо путь к файлу не совпадает с namespace по правилам PSR-4. Проверьте регистр букв: на Linux он важен.
• The openssl extension is required — расширение выключено в php.ini. Включите строку с openssl и перезапустите терминал.
• Failed to download ... curl error — нет сети или блокируется доступ к packagist.org. Проверьте прокси и корпоративный файрвол.
• Composer молча зависает на «Updating dependencies» — не хватает памяти при большом дереве зависимостей. Разово поднимите лимит: php -d memory_limit=-1 /usr/local/bin/composer update.

Что делать дальше

Базовая связка готова. Дальше смотрите в сторону трёх вещей. Первое — добавьте в .gitignore папку vendor, но composer.lock закоммитьте: коллеги получат ровно ваши версии по composer install. Второе — разделите require и require-dev: инструменты для тестов и линтеры ставятся флагом --dev и не попадают в продакшн через composer install --no-dev. Третье — для боевого сервера соберите оптимизированный автозагрузчик командой composer dump-autoload --optimize: она переводит PSR-4 в готовую classmap и ускоряет поиск классов.