Как обновлять Composer-зависимости в старом PHP-проекте

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

Безопасный подход простой: не обновлять всё сразу на рабочем сервере и не удалять composer.lock без причины.

Сначала посмотреть текущее состояние

Перед изменениями нужно понять, с чем работает проект: версия PHP, установленные пакеты, наличие lock-файла, ограничения в composer.json.

php -v
composer --version
composer validate
composer show --direct

Если composer.lock есть, это хорошо. Он фиксирует конкретные версии пакетов. На production обычно выполняют composer install, а не composer update.

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

composer update пересчитывает версии зависимостей и может поставить новые пакеты в рамках ограничений composer.json. В legacy-проекте это действие лучше делать только на тестовом окружении.

Проверить устаревшие пакеты

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

composer outdated --direct

Ключ --direct показывает прямые зависимости проекта. Это удобнее, чем сразу смотреть всё дерево, где много пакетов подтянуты другими библиотеками.

Проверить уязвимости

Если доступна современная версия Composer, полезно выполнить аудит. Он покажет известные уязвимости в установленных пакетах.

composer audit

Результат аудита — не повод слепо запускать update на production. Нужно понять, затронута ли используемая часть библиотеки и какая версия закрывает проблему.

Обновлять по одному направлению

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

composer update vendor/package --with-dependencies

После обновления нужно посмотреть diff composer.lock. Иногда за одним пакетом обновляется ещё несколько зависимостей. Это нормально, но такие изменения нужно видеть.

git diff composer.lock
git diff composer.json

Не игнорировать платформу PHP

Частая ситуация: локально стоит PHP 8.2, а сервер работает на PHP 7.4. Composer может подобрать зависимости под локальную версию, а на сервере они не запустятся. Для таких проектов в composer.json указывают platform.

{
    "config": {
        "platform": {
            "php": "7.4.33"
        }
    }
}

Это не заменяет обновление PHP, но помогает не поставить пакет, который требует более новую версию языка.

Проверить автозагрузку

После изменения зависимостей полезно пересобрать автозагрузку. Для рабочего окружения обычно используют оптимизированный autoloader.

composer dump-autoload -o

Если проект использует старые классы без namespace, в composer.json могут быть прописаны classmap или files. Такие секции нельзя удалять только потому, что они выглядят устаревшими.

{
    "autoload": {
        "classmap": [
            "legacy/classes"
        ],
        "files": [
            "legacy/helpers.php"
        ]
    }
}

Тестовый стенд перед production

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

• открывается главная страница;
• работает авторизация;
• отправляется форма;
• открывается админка;
• выполняются основные консольные команды;
• нет новых критических ошибок в логах.

php yii help
php yii migrate/history
tail -n 100 runtime/logs/app.log

План отката

Перед выкладкой на рабочий сервер должен быть понятный откат. Для Composer это обычно возврат composer.json и composer.lock к предыдущему коммиту, затем composer install.

git checkout HEAD~1 composer.json composer.lock
composer install --no-dev --prefer-dist --optimize-autoloader

Если вместе с обновлением были миграции базы, откат становится сложнее. Поэтому зависимости и изменения структуры данных лучше не смешивать без необходимости.

Рабочий порядок

1. Зафиксировать текущие версии PHP и Composer.
2. Проверить composer.json и composer.lock.
3. Запустить composer outdated --direct.
4. Запустить composer audit.
5. Обновить один пакет или небольшую группу.
6. Проверить diff composer.lock.
7. Прогнать проект на тестовом стенде.
8. Выложить composer.lock и выполнить composer install на сервере.
9. Проверить логи и основные сценарии.

Главная ошибка при работе с Composer в legacy-проекте — относиться к update как к безобидной технической операции. Это изменение кода, просто код находится в vendor. Значит, его нужно проверять так же внимательно, как собственные правки.