Composer: установка, composer.json и управление зависимостями
Composer управляет пакетами, от которых зависит PHP-проект, и генерирует автозагрузчик для классов. Разберём, как установить Composer, описать требования в composer.json и добиться того, чтобы разработчики, CI и сервер устанавливали один и тот же набор версий.
Composer для PHP: что он делает и где хранит зависимости
Вы указываете имя пакета и допустимую версию, а Composer подбирает совместимый набор пакетов с учётом их собственных зависимостей, версии PHP и доступных расширений. Например, HTTP-клиент может зависеть от пакета интерфейсов PSR. Composer установит оба, даже если в проекте явно указан только клиент.
composer.jsonописывает требования проекта, правила автозагрузки и другие настройки.composer.lockфиксирует подобранные версии прямых и транзитивных зависимостей. Храните его в Git для приложений, чтобы воспроизводить установку.vendor/содержит установленные пакеты и сгенерированный файлvendor/autoload.php. Обычно этот каталог исключают из Git.
Команды Composer запускают из корня проекта, где лежит composer.json. У каждого проекта может быть свой набор пакетов и версий, даже если все проекты используют одну глобальную установку Composer.
Установка Composer: PHP CLI и первый запуск
Для работы нужен PHP CLI. Начните с php -v и php --ini. Эти команды показывают версию интерпретатора и конфигурацию, которую он загружает в терминале. Веб-сервер может использовать другую версию PHP и другой php.ini.
На Windows запустите официальный установщик Composer для Windows, выберите нужный php.exe и откройте новый терминал после установки. На Linux и macOS используйте пакетный менеджер, если он предоставляет подходящий Composer 2, или официальный установщик. Для ручной установки скачайте установщик в текущий каталог как composer-setup.php и сверьте его SHA-384 с опубликованной контрольной суммой перед запуском. Следующие команды устанавливают Composer локально:
# Запускаем установщик после сверки контрольной суммы
php composer-setup.php
# Проверяем Composer и окружение
php composer.phar --version
php composer.phar diagnoseЗапись php composer.phar запускает файл через выбранный PHP CLI. Для глобальной команды composer на Linux или macOS поместите PHAR под именем composer в каталог из PATH и сделайте его исполняемым. Дальше в примерах используется глобальная команда. При локальной установке заменяйте composer на php composer.phar, указав путь к файлу, если он лежит вне проекта.
composer.json: требования к PHP, пакетам и автозагрузке
В новом проекте можно запустить composer init или создать файл вручную. Ниже конфигурация небольшого приложения с Monolog, PHPUnit для тестов и автозагрузкой собственных классов из src/.
{
"name": "example/php-handbook",
"require": {
"php": "~8.3.0 || ~8.4.0 || ~8.5.0",
"ext-json": "*",
"monolog/monolog": "^3.0"
},
"require-dev": {
"phpunit/phpunit": "^12.0"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}JSON требует двойных кавычек и не поддерживает комментарии или запятую после последнего поля. Двойная обратная косая черта в "App\\" записывает один символ \ в префиксе пространства имён.
requireзадаёт требования для запуска приложения, включая PHP и расширения.ext-jsonв примере объявляет использование JSON. В PHP 8 это расширение входит в стандартную поставку и всегда включено.require-devхранит инструменты разработки. При установке с--no-devPHPUnit вvendor/не попадёт.autoload.psr-4сопоставляет префикс пространства имён с каталогом. Для классов, используемых только в тестах, предусмотрен отдельный разделautoload-dev.
Ограничение ^3.0 разрешает версии от 3.0.0 до следующей мажорной версии, исключая 4.0.0. Для пакетов до 1.0 граница уже: ^0.3 допускает 0.3.x и исключает 0.4.0. Ограничение ~8.3.0 допускает патч-релизы ветки 8.3. Оператор || разрешает любую из перечисленных веток. Если проект готов принимать будущие минорные версии PHP 8, вместо перечисления можно указать ^8.3.
# Проверяем конфигурацию и выполняем первую установку
composer validate
composer installПри первой установке Composer подберёт версии и создаст composer.lock. Конфигурация PHPUnit из примера требует PHP 8.3 или новее и доступных расширений, среди которых DOM и mbstring.
Автозагрузка PSR-4 в приложении
Для класса App\HealthCheck из приведённой конфигурации создайте файл src/HealthCheck.php. Имя файла и регистр букв должны совпадать с именем класса. Несовпадение может остаться незаметным на файловой системе Windows и привести к ошибке на Linux.
<?php
declare(strict_types=1);
namespace App;
final class HealthCheck
{
public function status(): string
{
// Возвращаем короткий статус для проверки запуска.
return 'ok';
}
}В корне проекта создайте check.php. Этот сценарий загружает класс приложения и два класса из установленного пакета через один автозагрузчик.
<?php
declare(strict_types=1);
use App\HealthCheck;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
require __DIR__ . '/vendor/autoload.php';
// Пишем результат проверки в стандартный вывод.
$logger = new Logger('app');
$logger->pushHandler(new StreamHandler('php://stdout'));
$logger->info((new HealthCheck())->status());Запустите php check.php. В выводе появится запись журнала со статусом ok. После изменения правил autoload выполните composer dump-autoload. Добавление класса в уже настроенный каталог PSR-4 при обычной разработке ручной пересборки не требует. Директива declare(strict_types=1) относится к PHP-файлу и управляет строгой проверкой скалярных типов при вызовах из него. В каждый PHP-файл её добавляют отдельно.
Команды Composer для установки и обновления пакетов
| Команда | Когда применять |
|---|---|
composer install | Развернуть проект по существующему composer.lock. |
composer require symfony/console:^7.0 | Добавить зависимость приложения и обновить файлы конфигурации и блокировки. |
composer require --dev phpstan/phpstan | Добавить инструмент разработки. |
composer update monolog/monolog | Обновить выбранный пакет в рамках ограничений проекта. |
composer update | Заново подобрать версии всех зависимостей в разрешённых диапазонах. |
composer remove symfony/console | Удалить прямую зависимость и пакеты, которые больше никому не нужны. |
composer audit --locked | Проверить зафиксированные пакеты по известным уведомлениям об уязвимостях и сведениям о заброшенных пакетах. |
install берёт точные версии из composer.lock, если файл уже существует. update запускает новый подбор версий и записывает результат в lock-файл. После require, remove или update просмотрите изменения обоих файлов, запустите тесты и закоммитьте результат. Для предварительного просмотра можно выполнить composer update monolog/monolog --dry-run.
Если выбранному пакету мешает зафиксированная версия связанной зависимости, попробуйте composer update monolog/monolog -W. Флаг разрешает обновить также зависимости указанного пакета, включая те, которые проект объявляет напрямую. Проверьте итоговый diff: такой запуск может изменить больше одной записи в lock-файле.
PHP 8.3, 8.4 и 8.5: совместимость зависимостей
В конце 2026 года ветки PHP 8.3–8.5 поддерживаются. Для проекта, который заявляет совместимость со всеми тремя, минимальная версия определяет допустимый синтаксис. Например, перехватчики свойств появились в 8.4, а оператор конвейера |> — в 8.5. Если такой синтаксис попадёт в файл, загружаемый на PHP 8.3, интерпретатор остановится с ошибкой разбора.
Ограничение require.php задаёт диапазон версий для проекта. Если собрать зависимости на 8.5, Composer может выбрать пакет, требующий 8.4 или 8.5, даже когда сам проект объявляет поддержку 8.3. Для общего lock-файла подбирайте зависимости на минимальной целевой версии. Если это неудобно, задайте config.platform.php равным фактической минимальной версии, например 8.3.0, когда заявлена поддержка всей ветки 8.3. Composer будет использовать это значение при подборе пакетов.
# Ищем требования, которые блокируют переход на конкретную версию PHP
composer prohibits php 8.5.0 --locked
# Проверяем реальный PHP и расширения на целевой машине
composer check-platform-reqscheck-platform-reqs проверяет фактическое окружение без подстановки config.platform. Тесты на 8.3, 8.4 и 8.5 дополняют эту проверку: Composer видит заявленные требования пакетов, а тесты выявляют ошибки исполнения на каждой ветке.
Типичные ошибки Composer и порядок диагностики
- Терминал не находит
composer. Откройте новый терминал и проверьтеPATH. В PowerShell путь к исполняемому файлу покажетGet-Command composer. Если установлен локальный PHAR, запустите его черезphp composer.phar. - Пакет требует расширение, которого нет. Выполните
php -mиphp --ini, затем установите или включите нужное расширение для используемого PHP CLI. Если приложение работает через PHP-FPM, проверьте расширение и там. Флаг--ignore-platform-reqsпропускает проверки, поэтому установка может завершиться успешно, а приложение упасть при запуске. - Composer не может подобрать совместимые версии. Прочитайте в выводе цепочку требований. Чтобы узнать, что блокирует конкретную версию пакета, выполните, например,
composer prohibits monolog/monolog 3.0.0 --locked. Командаcomposer why monolog/monologпокажет, кто требует этот пакет в установленном наборе. - Lock-файл отстал от
composer.json. После ручной правки требований запуститеcomposer update имя/пакетадля изменённой зависимости и проверьте diff. Если менялись только метаданные и версии должны остаться прежними,composer update --lockобновит хеш lock-файла без смены версий пакетов. - Ошибка
Class not found. Проверьте наличиеvendor/autoload.php, префикс PSR-4, регистр пути и пространства имён. После изменения правил автозагрузки обновите её командойcomposer dump-autoload. Если класс принадлежит инструменту изrequire-dev, проверьте, не установлены ли зависимости с--no-dev.
Чек-лист для разработки, CI и сервера
- Объявите минимальную версию PHP и расширения, которые использует приложение. Проверьте
composer.jsonкомандойcomposer validate --strict. - Храните
composer.jsonиcomposer.lockвместе. Обновляйте пакеты целенаправленно и просматривайте изменения lock-файла перед коммитом. - В CI запускайте
composer installс зависимостями разработки и прогоняйте тесты на всех заявленных ветках PHP. Проверяйте сообщенияcomposer audit --locked. - Для продакшена устанавливайте зависимости из закоммиченного lock-файла и проверяйте платформу в окружении, где будет работать приложение.
# Устанавливаем зависимости приложения и оптимизируем автозагрузку
composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
# Проверяем PHP и расширения для продакшен-зависимостей
composer check-platform-reqs --no-devЕсли сборка выполняется в отдельном контейнере, запускайте проверку платформы в окружении с теми же PHP и расширениями, что и у приложения. После выкладки проверьте запуск приложения через его обычную точку входа.
Частые вопросы
Что выбрать для существующего проекта: composer install или composer update?
Для запуска проекта из репозитория используйте composer install. Если в репозитории есть composer.lock, команда установит зафиксированные версии. Composer update применяйте, когда хотите заново подобрать версии и записать результат в lock-файл.
Нужно ли коммитить composer.lock в Git?
Для приложения коммитьте composer.lock вместе с composer.json. У библиотеки lock-файл может фиксировать окружение её собственных тестов. При установке библиотеки Composer подбирает её зависимости по требованиям composer.json в контексте проекта-потребителя.
Почему Composer видит другую версию PHP, чем сайт?
Composer работает через PHP CLI, а сайт может обслуживаться другой версией PHP-FPM или модулем веб-сервера. Проверьте php -v и php --ini в терминале, затем сравните версию PHP и набор расширений с конфигурацией сайта.