Composer: управление версиями зависимостей
В Composer диапазон версий определяет, какие релизы допустимы, а файл блокировки фиксирует результат выбора. Разберём, как подобрать ограничение, обновить один пакет и найти причину конфликта версий.
Что задаёт composer.json и что фиксирует composer.lock
В composer.json вы объявляете требования проекта. В require указывают пакеты и расширения, нужные приложению, а в require-dev — инструменты разработки и тестирования. При разрешении зависимостей Composer одновременно учитывает требования проекта, требования самих пакетов и доступную платформу. Поэтому последнее подходящее по номеру обновление может оказаться несовместимым с другими пакетами.
В composer.lock записываются выбранные версии прямых и транзитивных зависимостей. Если файл существует, composer install устанавливает зафиксированные версии. Если файла нет, команда разрешает зависимости и создаёт его. composer update заново разрешает зависимости в пределах объявленных ограничений и записывает результат в lock-файл.
В приложении храните оба файла в Git. Тогда CI, разработчики и production получают один и тот же набор версий при установке с одинаковыми параметрами. У библиотеки lock-файл может фиксировать её собственное окружение разработки, но при установке библиотеки Composer использует lock-файл приложения-потребителя. На совместимость библиотеки влияют ограничения в её composer.json.
Как читать ограничения версий
Для стабильных релизов по SemVer исправления выходят в patch-версиях, обратно совместимые возможности — в minor-версиях, несовместимые изменения — в major-версиях. Composer вычисляет диапазон по номеру релиза. Убедиться, что библиотека действительно сохранила совместимость, помогают журнал изменений и тесты.
В таблице границы показаны для стабильных релизов.
| Ограничение | Какие версии подходят | Когда использовать |
|---|---|---|
^1.4.2 | >=1.4.2 <2.0.0 | Нужен минимум 1.4.2 и допустимы следующие релизы ветки 1.x. |
~1.4.2 | >=1.4.2 <1.5.0 | Обновления ограничены серией 1.4. |
~1.4 | >=1.4.0 <2.0.0 | Допустимы minor-обновления до следующей major-версии. |
1.4.* | >=1.4.0 <1.5.0 | Подходит любой стабильный релиз серии 1.4. |
^0.3.2 | >=0.3.2 <0.4.0 | Пакет ещё в серии 0.x, поэтому диапазон уже. |
1.4.2 | Только 1.4.2 | Временная фиксация, например на время исправления регрессии. |
* | Любая версия, допустимая с учётом остальных требований и стабильности | Только если приложению действительно подходит любой релиз, включая следующий major. |
Для зависимости, которая соблюдает SemVer, обычно удобно начать с ^. Нижняя граница должна включать релиз, где появился нужный метод или вышло обязательное исправление. У версий до 1.0 каретка останавливается перед изменением первой ненулевой позиции. Поэтому ^0.0.3 допускает стабильную 0.0.3, а 0.0.4 уже выходит за диапазон.
Пробел или запятая объединяют условия по «и», а || задаёт альтернативы. Например, >=1.4.2 <2.0 описывает один диапазон, а ^1.4 || ^2.0 — две поддерживаемые линии. Если библиотека объявляет обе линии, прогоняйте тесты с каждой из них.
Стабильность, dev-ветки и псевдонимы
По умолчанию minimum-stability равен stable. Если конкретному пакету нужен предварительный релиз, разрешите его в требовании корневого проекта. Например, ^2.0@RC допускает для этого пакета версии уровня RC и стабильные версии, подходящие по диапазону. prefer-stable помогает предпочесть стабильный релиз среди допустимых вариантов, когда разрешены предварительные версии.
Ветка main доступна как dev-main, а ветка 2.1 — как 2.1.x-dev. Lock-файл фиксирует ревизию установленной ветки, но при следующем разрешённом обновлении Composer может выбрать более свежий коммит. Владелец пакета может объявить в composer.json самой ветки, к какой линии разработки она относится.
{
"extra": {
"branch-alias": {
"dev-main": "2.1.x-dev"
}
}
}С таким псевдонимом корневой проект может запросить 2.1.*@dev. Псевдоним позволяет сопоставить ветку с числовым диапазоном. Её стабильность остаётся dev, а содержимое меняется вместе с веткой. Когда выйдет подходящий стабильный тег, уберите @dev и обновите пакет. Если dev-зависимость объявлена внутри библиотеки, допуск нужной стабильности требуется в корневом приложении, которое её устанавливает.
Как обновить один пакет или перейти на новый major
Начните с точечного обновления. Например, для приложения, в котором уже установлен monolog/monolog, можно предварительно посмотреть план и затем применить его.
# Показывает план обновления без установки.
composer update monolog/monolog --dry-run
# Обновляет пакет в пределах текущего ограничения.
composer update monolog/monologПри частичном обновлении часть пакетов остаётся на версиях из lock-файла. Если обновлению мешают зависимости выбранного пакета, повторите команду с --with-dependencies (-w). Если нужно разрешить обновление и тех его зависимостей, которые сам проект перечисляет среди прямых требований, используйте --with-all-dependencies (-W). После этого просмотрите весь diff composer.lock.
Если в манифесте записано ^2.0, обычное обновление не выберет 3.x. Для перехода на следующую линию измените ограничение. Команда ниже подходит для пакета из require после подготовки к переходу на 3.x.
# Меняет требование и разрешает обновить связанные зависимости.
composer require 'monolog/monolog:^3.0' -WПосле смены major-версии проверьте затронутые вызовы, конфигурацию и тесты. Для обычного production-развёртывания устанавливайте уже проверенный набор через composer install --no-dev --optimize-autoloader.
Как задать требования к PHP и расширениям
Описывайте платформу так же явно, как библиотеки. В этом примере приложение поддерживает PHP 8.3–8.5, использует расширение mbstring и разрешает обновления в линии Monolog 3.x. Верхняя граница PHP отражает диапазон, заявленный для этого приложения.
{
"require": {
"php": ">=8.3 <8.6",
"ext-mbstring": "*",
"monolog/monolog": "^3.0"
},
"config": {
"platform": {
"php": "8.3.0"
}
}
}Для ext-mbstring звёздочка означает, что важно наличие расширения и его версия не ограничена. config.platform.php заставляет Composer разрешать зависимости как для указанной версии PHP. Это помогает, если разработчик работает на PHP 8.5, а приложение должно устанавливаться и на PHP 8.3. Если минимальная версия в инфраструктуре выше, укажите её фактический номер.
Проверяйте реальную платформу командой composer check-platform-reqs --no-dev в окружении развёртывания. Она сверяет PHP и расширения с требованиями установленных пакетов без подмены из config.platform. Для приложения, заявляющего поддержку PHP 8.3–8.5, прогоните CI на всех трёх версиях. Если CLI и PHP-FPM используют разные конфигурации, отдельно проверьте расширения, доступные веб-приложению.
Как расследовать конфликт версий
Если Composer пишет, что требования невозможно удовлетворить, сначала выясните, кто требует текущую версию пакета и что мешает поставить целевую. Используйте конкретный номер релиза, чтобы ответ был однозначным.
# Показывает, какие пакеты требуют Monolog.
composer why monolog/monolog
# Показывает ограничения, блокирующие Monolog 3.0.0.
composer prohibits monolog/monolog 3.0.0
# Показывает требования, несовместимые с PHP 8.5.0.
composer prohibits php 8.5.0Если манифест требует ^2.0, а другой пакет допускает только ^3.0, у диапазонов нет пересечения. Проверьте, можно ли обновить прямую зависимость или выбрать совместимый выпуск второго пакета. Если диапазоны пересекаются, но Composer указывает на зафиксированную версию при частичном обновлении, добавьте блокирующий пакет в список обновляемых или примените подходящий флаг -w или -W. При конфликте платформы сверьте требования пакетов с версией PHP и набором расширений в целевом окружении.
Чек-лист перед коммитом обновления
- Проверьте нижнюю границу зависимости и диапазон допустимых релизов. Для временной фиксации версии запишите причину и условие, при котором её можно снять.
- Обновите нужные пакеты и просмотрите изменения прямых и транзитивных версий в
composer.lock. - Запустите
composer validate --strictдля проверки манифеста и его согласованности с lock-файлом. Проверьте зафиксированные зависимости черезcomposer audit --locked. - Прогоните тесты на поддерживаемых версиях PHP. Для публикуемой библиотеки дополнительно проверьте нижние границы зависимостей через
composer update --prefer-lowest --prefer-stableв отдельной задаче CI. - Для приложения закоммитьте
composer.jsonиcomposer.lockвместе. При развёртывании используйтеcomposer installи проверьте требования к платформе в целевом окружении.
Частые вопросы
Чем ^1.4.2 отличается от ~1.4.2 в Composer?
Оба ограничения начинаются с 1.4.2. Каретка допускает стабильные релизы до 2.0.0, а тильда с тремя числами — до 1.5.0. Верхние границы исключены.
Нужно ли коммитить composer.lock?
Для приложения — да. Файл фиксирует прямые и транзитивные зависимости, чтобы composer install воспроизводил выбранный набор. В репозитории библиотеки lock-файл может фиксировать окружение её разработки. При установке библиотеки используется lock-файл приложения-потребителя.
Как обновить один пакет в Composer?
Выполните composer update с именем пакета. Если зафиксированные версии его зависимостей мешают обновлению, используйте -w, а если среди них есть прямые требования проекта — -W. Проверьте итоговый diff composer.lock и прогоните тесты.