Composer в PHP: от первой команды до рабочего проекта

Composer помогает подключать готовые PHP-библиотеки и держать их версии под контролем. Вместо ручного скачивания архивов вы описываете зависимости проекта, а Composer находит совместимый набор, устанавливает его и создаёт автозагрузчик. Это одинаково полезно для небольшого скрипта, собственного сайта и большого приложения.

Примеры рассчитаны на Composer 2 и PHP 8.2 или новее в ветке 8.x. Команды выполняются в терминале из каталога проекта. PHP-код сохраняется в файлы, JSON — в composer.json. Кнопка над блоком копирует только его содержимое. Учебные ответы API ниже заранее заданы: Composer и PHP запускаются у вас локально, сама страница пакеты не устанавливает.

1. Как Composer собирает проект

Допустим, сайту нужен HTTP-клиент Guzzle и журнал событий Monolog. Эти библиотеки тоже могут использовать другие пакеты. Вы указываете прямые зависимости, а Composer рассчитывает весь граф: версии должны одновременно удовлетворять требованиям проекта, библиотек, PHP и расширений.

Процесс выглядит так: требования → подбор совместимых версий → lock-файл → установка в vendor → подключение автозагрузчика. При наличии lock-файла обычная установка берёт версии из него. Composer не становится частью каждого HTTP-запроса: приложению во время работы обычно нужны установленные библиотеки и автозагрузчик.

Подробнее: Composer: введение и зависимости.

2. Установка и проверка окружения

Сначала убедитесь, что PHP доступен из терминала. Версия PHP веб-сервера и версия PHP командной строки могут различаться.

php --version
php --ini
php -m

Windows. Скачайте официальный Composer-Setup.exe, выберите нужный php.exe и после установки откройте новый терминал: старое окно может ещё не видеть обновлённый PATH.

Linux и macOS. На той же странице загрузки есть актуальные команды установки с проверкой SHA-384. Копируйте их целиком в день установки: контрольная сумма установщика меняется. Установленный локально composer.phar можно вызывать через PHP без глобальной установки.

composer --version
composer diagnose

Если используете локальный PHAR, эквивалент первой команды:

php composer.phar --version

Во всех дальнейших примерах composer тогда заменяется на php /путь/к/composer.phar. Не путайте требования самого Composer и выбранных библиотек: работающий менеджер пакетов ещё не означает, что окружение подходит приложению.

3. Первый проект за несколько шагов

Создайте отдельную папку. Следующие команды подходят для PowerShell и обычной оболочки Linux/macOS.

mkdir composer-first
cd composer-first
composer init

init задаст вопросы о проекте. Для имени используйте, например, demo/composer-first, тип — project; интерактивный поиск зависимостей можно пропустить. Затем установите библиотеку журнала событий:

composer require "monolog/monolog:3.*"

Команда добавит требование в JSON, выберет совместимую версию, обновит lock-файл и установит пакет вместе с его зависимостями. Если подбор не удался, сначала прочитайте конкретный конфликт в выводе. Создайте рядом с composer.json файл hello.php:

<?php
declare(strict_types=1);

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

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

$log = new Logger('hello');
$log->pushHandler(new StreamHandler('php://stdout', Level::Info));
$log->info('Composer работает', ['lesson' => 1]);

Запустите файл:

php hello.php

Ожидаемый результат: строка журнала с текстом «Composer работает», уровнем INFO и полем lesson. Дата и служебное оформление зависят от запуска. Если убрать подключение автозагрузчика, PHP не узнает класс Monolog\Logger.

Для команд с ограничениями версий используются кавычки. В коротких примерах здесь выбран синтаксис 3.*, чтобы не зависеть от особенностей передачи символа ^ через composer.bat в PowerShell. Ограничения с ^ далее показаны непосредственно в JSON.

4. Install, update и composer.lock

После клонирования проекта выполняйте composer install. При существующем lock-файле команда устанавливает зафиксированные версии. Если lock-файла нет, Composer подберёт зависимости и создаст его — это уже не воспроизведение заранее проверенного набора.

composer install

Для запланированного обновления используйте update. Команда заново подбирает версии в разрешённых диапазонах и переписывает lock-файл. Обычно удобнее начать с конкретного пакета и посмотреть план:

composer update monolog/monolog --with-all-dependencies --dry-run

Если план подходит, выполните обновление:

composer update monolog/monolog --with-all-dependencies

--with-all-dependencies, сокращённо -W, разрешает менять также связанные зависимости, включая корневые. Ограничения composer.json продолжают действовать. После команды посмотрите изменения lock-файла и проверьте приложение. Обычный composer update без имени пакета пересматривает весь набор.

Пример .gitignore:

/vendor/
/auth.json
/.env
/var/log/

Подробнее: Composer: базовый рабочий процесс.

Подробнее: Нужно ли хранить vendor в Git.

5. Как читать ограничения версий

Диапазон задаёт, какие версии допустимы, а lock-файл хранит уже выбранную. Ниже — границы для обычных стабильных релизов.

Пробел между сравнениями означает «и»: >=2.4 <3.0. По умолчанию разрешены стабильные релизы. Стабильность и диапазон — разные условия; ради одного пакета не стоит бездумно переводить весь проект на minimum-stability: dev.

Даже разрешённое обновление нужно тестировать: диапазон версий выражает ожидание совместимости, но не доказывает отсутствие регрессий.

Подробнее: Composer: версии, диапазоны и стабильность.

6. Автозагрузка своих классов: PSR-4

Composer загружает не только сторонние библиотеки, но и ваши классы. Правило App\ → src/ означает: класс App\Service\Mailer находится в src/Service/Mailer.php. Внутри файла должны совпадать пространство имён App\Service и имя класса Mailer.

Добавьте в корневой JSON секцию autoload, сохраняя остальные поля:

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

В JSON обратный слеш экранируется: два символа \\ в записи обозначают один. После изменения правил выполните:

composer dump-autoload

В точке входа один раз подключите vendor/autoload.php. Для файла в корне проекта:

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

Для public/index.php путь будет другим: dirname(__DIR__) . '/vendor/autoload.php'. Относительный путь нужно считать от расположения самого PHP-файла.

Подробнее: Схема composer.json: автозагрузка.

7. Готовый PHP-проект: шесть сценариев

Теперь соединяем зависимости, собственный класс и запуск через Composer. Guzzle обрабатывает HTTP-ответ, класс UserApi извлекает имя пользователя, Monolog пишет диагностическое событие. Чтобы результат не зависел от доступности внешнего сервиса, используем официальный MockHandler: реальные библиотеки работают с заранее заданными ответами, сетевой запрос не отправляется.

Скачать PHP-проект ZIP

В архиве: composer.json, composer.lock, demo.php, src/UserApi.php и инструкция. Папка vendor не вложена — её создаст установка. После распаковки откройте терминал в каталоге, где лежит composer.json.

composer install
composer run demo -- ok

Результат: строка «Александр» и код завершения 0. Во время первой установки нужен интернет для загрузки пакетов; после установки сами шесть демонстраций работают без сети.

Распакуйте этот проект в отдельную папку: он не требует переноса файлов из первого примера с hello.php.

composer-demo/
├── composer.json
├── composer.lock
├── demo.php
├── src/
│   └── UserApi.php
└── vendor/  ← создаётся после install

Файл composer.json — целиком:

{
  "name": "ae-nekrasov/composer-demo",
  "description": "Учебный пример Composer, Guzzle и Monolog",
  "type": "project",
  "license": "MIT",
  "require": {
    "php": "^8.2",
    "guzzlehttp/guzzle": "^7.9",
    "monolog/monolog": "^3.0"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  },
  "scripts": {
    "demo": "@php demo.php",
    "lint": [
      "@php -l demo.php",
      "@php -l src/UserApi.php"
    ]
  },
  "config": {
    "sort-packages": true
  }
}

Файл src/UserApi.php — целиком:

<?php
declare(strict_types=1);

namespace App;

use GuzzleHttp\ClientInterface;

final class UserApi
{
    public function __construct(private ClientInterface $http) {}

    public function name(int $id): string
    {
        if ($id < 1) {
            throw new \InvalidArgumentException('ID должен быть положительным.');
        }
        $response = $this->http->request('GET', 'users/' . $id);
        $data = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
        if (!is_array($data) || !isset($data['name']) || !is_string($data['name'])) {
            throw new \UnexpectedValueException('В ответе нет строкового поля name.');
        }
        return $data['name'];
    }
}

Сначала проверяется аргумент, затем выполняется запрос и разбирается JSON. Корректный JSON ещё не означает нужную структуру: объект без строкового поля name тоже отклоняется.

<?php
declare(strict_types=1);

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

use App\UserApi;
use GuzzleHttp\Client;
use GuzzleHttp\Exception\ConnectException;
use GuzzleHttp\Exception\RequestException;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;
use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;

$scenario = $argv[1] ?? 'ok';
$fixtures = [
    'ok' => new Response(200, ['Content-Type' => 'application/json'], '{"name":"Александр"}'),
    '404' => new Response(404, [], '{"error":"not found"}'),
    '503' => new Response(503, [], '{"error":"unavailable"}'),
    'json' => new Response(200, [], '{broken json'),
    'schema' => new Response(200, [], '{"id":1}'),
    'network' => new ConnectException('Смоделирована ошибка соединения.', new Request('GET', 'https://api.example.test/users/1')),
];
if (!isset($fixtures[$scenario])) {
    fwrite(STDERR, "Сценарии: ok, 404, 503, json, schema, network\n");
    exit(2);
}

// MockHandler возвращает заданный ответ. Реального сетевого запроса нет.
$client = new Client([
    'base_uri' => 'https://api.example.test/',
    'timeout' => 5.0,
    'http_errors' => true,
    'handler' => HandlerStack::create(new MockHandler([$fixtures[$scenario]])),
]);
$log = new Logger('composer-demo');
$log->pushHandler(new StreamHandler('php://stderr', Level::Warning));

try {
    echo (new UserApi($client))->name(1) . PHP_EOL;
} catch (ConnectException $e) {
    $log->warning('Сеть недоступна', ['exception' => get_class($e)]);
    fwrite(STDERR, "Не удалось соединиться с API. Повторите позже.\n");
    exit(1);
} catch (RequestException $e) {
    $status = $e->getResponse()?->getStatusCode();
    $log->warning('HTTP-ошибка', ['status' => $status]);
    fwrite(STDERR, 'API вернул ошибку HTTP ' . ($status ?? 'без ответа') . PHP_EOL);
    exit(1);
} catch (JsonException | UnexpectedValueException $e) {
    $log->warning('Неверный формат ответа', ['exception' => get_class($e)]);
    fwrite(STDERR, "API вернул некорректные данные.\n");
    exit(1);
}

Проверьте остальные ветки по одной. Ожидаемые ошибки специально завершаются кодом 1. Поэтому сообщение Composer о ненулевом коде скрипта в этих сценариях означает, что учебная ветка отказа сработала.

composer run demo -- 404

composer run demo -- 503

composer run demo -- json

composer run demo -- schema

composer run demo -- network

Проект проверен 6 ноября 2026 года на PHP 8.3.33 и Composer 2.10.3. В lock-файле зафиксированы Guzzle 7.16.1 и Monolog 3.12.1. Это версии проверенного набора, а не обещание использовать всегда самые новые релизы.

Подробнее: Guzzle: MockHandler и тестирование HTTP.

8. Исключения: что именно мы ловим

Ошибка команды composer install и исключение PHP во время работы приложения возникают на разных этапах. try/catch в demo.php не исправит несовместимые зависимости при установке. И успешная установка не гарантирует, что внешний API всегда ответит корректно.

В Guzzle ConnectException не следует рассчитывать поймать только через RequestException. Пример использует request(), стандартный стек HandlerStack::create() и http_errors: true: HTTP 4xx/5xx становятся исключениями. При http_errors: false статус нужно проверять самостоятельно. У PSR-18-вызова sendRequest() другие правила обработки HTTP-статусов.

Веб-приложение должно показывать посетителю короткое сообщение, а технические детали оставлять в журнале. Не отправляйте в публичный ответ полный stack trace, токены и тело конфиденциального ответа. Для реального API замените учебный адрес на адрес своего сервиса, уберите handler с MockHandler, оставьте timeout и проверьте ожидаемую схему ответа. api.example.test — учебное имя, работающего API по нему нет.

Подробнее: Guzzle: иерархия исключений.

Подробнее: Guzzle: настройка http_errors.

9. Dev-зависимости и команды проекта

Библиотека, необходимая приложению при работе, относится к require. Тестовый раннер и анализатор кода обычно относятся к require-dev. Например, для учебной среды PHP 8.2+ можно установить PHPUnit ветки 11:

composer require --dev "phpunit/phpunit:11.*"

Требования этой ветки приведены в официальном руководстве PHPUnit 11.5. Это пример выбора совместимой ветки, а не рекомендация всегда оставаться на ней. Требования новой основной версии инструмента проверяйте перед переходом. Добавьте в существующую секцию scripts команды проекта:

{
  "scripts": {
    "demo": "@php demo.php",
    "lint": [
      "@php -l demo.php",
      "@php -l src/UserApi.php"
    ],
    "test": "phpunit"
  }
}

test имеет смысл после добавления PHPUnit и тестов. В скачиваемом проекте есть demo и lint; фиктивного тестового набора там нет. Выполнение:

composer run lint
composer run demo -- ok

@php выбирает PHP, которым запущен Composer. Аргументы после -- передаются вашему скрипту. Исполняемые файлы пакетов лежат в vendor/bin; Composer scripts помогает вызывать их одинаково в разных системах.

Хуки post-install-cmd и post-update-cmd запускаются на соответствующих этапах; install без lock-файла проходит через события обновления. Автоматически исполняются scripts корневого проекта, а не scripts каждой библиотеки. Плагины — отдельный механизм выполнения кода.

Подробнее: Composer: scripts и события.

Подробнее: Composer: команды пакетов в vendor/bin.

10. Частые ошибки и порядок проверки

Начинайте с первого конкретного сообщения Problem, а не с последней строки об общем сбое. Сначала определите этап: запуск Composer, подбор зависимостей, скачивание, выполнение scripts или запуск PHP.

composer --working-dir="path/to/project" install

composer why psr/log --tree
composer why-not monolog/monolog 3.0.0 --tree

composer diagnose -vvv

Подробнее: Composer: устранение неполадок.

11. Версия PHP и расширения сервера

Работающая установка на ноутбуке не доказывает совместимость с сервером. Например, локально PHP 8.3, а целевая среда — PHP 8.2. В composer.json можно моделировать целевую версию при подборе пакетов:

{
  "config": {
    "platform": {
      "php": "8.2.0"
    }
  }
}

Это фрагмент для объединения с существующим config. Значение должно соответствовать поддерживаемой вами минимальной среде. После изменения требуется пересмотреть lock-файл и проверить приложение.

config.platform не переключает PHP и не устанавливает расширения. Проверьте реальную среду отдельной командой — она игнорирует подмену platform:

composer check-platform-reqs

В production без dev-пакетов используйте composer check-platform-reqs --no-dev. Проверка CLI не заменяет сверку версии и расширений PHP-FPM или Apache, который обслуживает сайт.

Подробнее: Composer: config.platform.

12. Установка на сервере и в CI

Для развёртывания приложения нужен проверенный lock-файл из репозитория. Зависимости устанавливают в подготовленном каталоге релиза или на этапе сборки. Обновление версий лучше выполнять в разработке с проверками, затем переносить готовый результат.

composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

• --no-dev исключает зависимости и автозагрузку разработки.
• --prefer-dist предпочитает готовые дистрибутивы пакетов.
• --optimize-autoloader строит оптимизированную карту классов.
• --no-interaction не задаёт интерактивных вопросов; нужная конфигурация должна быть подготовлена заранее.

Затем проверьте требования среды и известные проблемы зависимостей:

composer check-platform-reqs --no-dev
composer audit --locked

Аудит lock-файла охватывает зафиксированный набор, включая dev-зависимости. Если проверяете только набор production, используйте composer audit --locked --no-dev. Это не заменяет тесты приложения.

Флаг --classmap-authoritative строже обычной оптимизации: отсутствующий в карте класс считается отсутствующим. Не включайте его автоматически, если приложение создаёт классы во время работы. Для большинства стартовых проектов достаточно -o.

Если Composer недоступен на хостинге, vendor можно включить в артефакт сборки, подготовленный в совместимой среде. Проверьте фактическую целевую платформу, права и путь к автозагрузчику. Не размещайте auth.json и другие секреты в публичном каталоге сайта.

Подробнее: Composer: оптимизация автозагрузчика.

13. Аудит, плагины и приватные пакеты

Пакеты — исполняемый код. Composer plugins и scripts могут выполнять действия с правами пользователя, который запустил установку. Изучайте доверенность проекта и разрешайте только нужные плагины. Для первоначального разбора чужого проекта в изолированной среде можно отключить оба механизма:

composer install --no-plugins --no-scripts

Эта команда может пропустить необходимую настройку приложения и не делает весь исходный код безопасным. Не запускайте Composer от администратора или root без конкретной необходимости.

Если аудит или установка сообщает об уязвимом пакете, прочитайте описание проблемы, найдите исправленную версию, выясните блокирующее требование через why-not и обновите зависимость. В новых версиях Composer настройки политик меняются; сверяйте их с документацией установленной версии. Постоянное выключение проверок — не исправление уязвимости.

Для приватного репозитория описание источника и секрет доступа должны быть разделены. Токен храните в исключённом из Git auth.json или передавайте через секрет CI в COMPOSER_AUTH. Не вставляйте его в публичный composer.json, команды из статьи или скриншоты журнала. Репозитории зависимостей автоматически не наследуются: нужный частный источник задают в корневом проекте.

Подробнее: Composer: установка недоверенных пакетов.

Подробнее: Composer: доступ к приватным пакетам.

Подробнее: Composer: репозитории.

14. Шпаргалка на каждый день

Выберите действие, затем копируйте нужную команду. Удаление пакета и обновление зависимостей меняют проект; не выполняйте весь список подряд.

После удаления пакета уберите или замените использующий его код. Composer меняет зависимости, но не переписывает приложение за вас.

Обычный цикл работы: изменить зависимость → посмотреть diff composer.json и composer.lock → запустить проверки и нужные сценарии → сохранить оба файла → установить проверенный набор в следующем окружении.

Подробнее: Официальный справочник команд Composer.

15. Источники и следующий шаг

Основные материалы, к которым удобно возвращаться:

• Документация Composer — вход в руководства и справочники.
• Установка Composer — актуальный установщик и проверка его целостности.
• Схема composer.json — назначение полей конфигурации.
• Документация Guzzle — HTTP-клиент, настройки, исключения и тестирование.
• Руководство Monolog — журналирование и обработчики.

Для практики скачайте проект, запустите успешный сценарий, затем каждую ошибку по отдельности. Найдите соответствующий catch и измените учебный ответ. После этого добавьте своё поле в ответ и проверку его типа: так становится видно, какую часть работы выполняет Composer, какую — библиотека, а какую — ваш код.

Скачать проект с шестью сценариями · Вернуться к первому запуску