PHPTime

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 локально:

Shell
# Запускаем установщик после сверки контрольной суммы
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/.

JSON
{
  "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-dev PHPUnit в 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.

Shell
# Проверяем конфигурацию и выполняем первую установку
composer validate
composer install

При первой установке Composer подберёт версии и создаст composer.lock. Конфигурация PHPUnit из примера требует PHP 8.3 или новее и доступных расширений, среди которых DOM и mbstring.

Автозагрузка PSR-4 в приложении

Для класса App\HealthCheck из приведённой конфигурации создайте файл src/HealthCheck.php. Имя файла и регистр букв должны совпадать с именем класса. Несовпадение может остаться незаметным на файловой системе Windows и привести к ошибке на Linux.

PHP
<?php
declare(strict_types=1);

namespace App;

final class HealthCheck
{
    public function status(): string
    {
        // Возвращаем короткий статус для проверки запуска.
        return 'ok';
    }
}

В корне проекта создайте check.php. Этот сценарий загружает класс приложения и два класса из установленного пакета через один автозагрузчик.

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 будет использовать это значение при подборе пакетов.

Shell
# Ищем требования, которые блокируют переход на конкретную версию PHP
composer prohibits php 8.5.0 --locked

# Проверяем реальный PHP и расширения на целевой машине
composer check-platform-reqs

check-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 и сервера

  1. Объявите минимальную версию PHP и расширения, которые использует приложение. Проверьте composer.json командой composer validate --strict.
  2. Храните composer.json и composer.lock вместе. Обновляйте пакеты целенаправленно и просматривайте изменения lock-файла перед коммитом.
  3. В CI запускайте composer install с зависимостями разработки и прогоняйте тесты на всех заявленных ветках PHP. Проверяйте сообщения composer audit --locked.
  4. Для продакшена устанавливайте зависимости из закоммиченного lock-файла и проверяйте платформу в окружении, где будет работать приложение.
Shell
# Устанавливаем зависимости приложения и оптимизируем автозагрузку
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 и набор расширений с конфигурацией сайта.

Справка по теме

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин