composer-upgrade

Composer のアップグレード

アップグレードのワークフロー

PHP プロジェクトをアップグレードする際は、次の手順に従ってください。

1. セキュリティ問題を確認する → composer audit — ここでの修正を最優先します
2. 古くなっているパッケージを特定する → composer outdated --format=json
3. 優先順位を付ける — CVE があり、かつ古くなっているパッケージを最初に対応します。references/audit.md を参照してください
4. 阻害要因を診断する → composer why-not vendor/package version — 更新を妨げているサブパッケージがあれば記録します
5. 依存関係を追跡する → composer why vendor/package
6. パッケージを更新する → composer update vendor/package — 阻害要因がある場合は、特定したパッケージを指定します：composer update vendor/package blocker/one blocker/two
7. テストする
8. 制約を厳格化する → composer bump（アプリケーションのみ）
9. 再監査する → composer audit を実行し、すべての勧告が解決されたことを確認します

すべてのフラグ（非対話型で使用するグローバルフラグ --no-interaction --no-progress --no-ansi を含む）については、references/commands.md を参照してください。 マージコンフリクトの解決を含む詳細な方法については、references/upgrade-workflow.md を参照してください。 セキュリティ監査の詳細、重大度の段階、優先順位を付けたパッケージリストの作成方法については、references/audit.md を参照してください。

composer.lock のマージコンフリクトを解決する

composer.lock でマージコンフリクトが発生した場合は、scripts/diff_lock.py を使用して両方の側を比較し、差分を調整するために必要なコマンドを生成します。

マージコンフリクトが発生しているとき：

# Compare HEAD vs MERGE_HEAD automatically and output composer commands
python3 scripts/diff_lock.py --conflict

# Human-readable summary of what changed
python3 scripts/diff_lock.py --conflict --format=summary

任意の 2 つのブランチまたはファイルを比較する場合：

python3 scripts/diff_lock.py main:composer.lock feature-branch:composer.lock
python3 scripts/diff_lock.py HEAD:composer.lock MERGE_HEAD:composer.lock
python3 scripts/diff_lock.py old.lock new.lock

このスクリプトは、パッケージをソースの状態からターゲットの状態に移行する composer require / composer remove コマンドを出力します。生成されたコマンドを実行してから、結果をコミットしてください。

詳しい手順については、references/upgrade-workflow.md の「ワークフロー：composer.lock のマージコンフリクト」を参照してください。

主要なコマンド

すべてのフラグとバージョン制約のクイックリファレンスについては、references/commands.md を参照してください。

composer outdated

composer outdated --format=json           # preferred when parsing output (fewer tokens)
composer outdated --direct --format=json  # only direct deps

赤 = メジャーアップデート（破壊的変更の可能性が高い）。黄色 = マイナー／パッチアップデート（安全）。! = SemVer の安全性が保証されません。

composer why-not

composer why-not vendor/package 2.0      # what prevents this upgrade
composer why-not php 8.2                 # what blocks a PHP version bump

出力には依存関係の連鎖、つまり競合するバージョンを要求しているパッケージが表示されます。

composer why

composer why vendor/package              # which installed packages depend on this one

composer update

composer update vendor/package --no-interaction --no-progress --no-ansi
composer update vendor/package --dry-run --no-interaction --no-ansi   # preview first

# If blocked, first identify which sub-dependencies are preventing the update:
composer why-not vendor/package 2.0
# Then include only those specific blockers in the update command:
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

よくあるパターン

「X を更新できないのはなぜですか？」

composer why-not vendor/package 3.0

出力から制約を設けているパッケージを特定し、そのパッケージ自体を更新できるか確認してください。

「PHP のバージョンアップグレードを妨げているものは何ですか？」

composer why-not php 8.2

php: ^8.2 の制約がないパッケージをすべて、阻害度の高い順に表示します。

「安全に段階的にアップグレードする」

直接依存関係は一度に 1 つずつ更新し、まず --dry-run を実行してください。

composer update vendor/package --dry-run --no-interaction --no-ansi
composer update vendor/package --no-interaction --no-progress --no-ansi

阻害要因がある場合は、composer why-not を使って更新を妨げている具体的なパッケージを特定し、それらだけを更新コマンドに指定してください。

composer why-not vendor/package 2.0
# → reveals blocker/one and blocker/two are preventing the update
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

メジャーバージョンの制約を引き上げる

composer.json を手動で編集するのではなく、composer require を使用してください。制約の更新とロックファイルの解決を一度に行えます。

composer require vendor/package:"^3.0" --dry-run --no-interaction --no-ansi
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

リスクの高いアップグレード（認証、権限、データベース層）では、コミット前にテストできるよう、二重の制約を使用してください。

# Allow both old and new major versions while testing
composer require vendor/package:"^2.5.0|^3.0" --no-interaction --no-progress --no-ansi
# If tests pass, lock in the new version:
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

詳しくは、references/upgrade-workflow.md の「メジャーバージョンアップグレードの手法」を参照してください。

アップグレード後に制約を厳格化する（アプリケーション）

composer bump                  # raise lower bounds in composer.json to installed versions
composer bump --dev-only       # only require-dev (safe for libraries too)

変更前："symfony/console": "^6.0" → 変更後："symfony/console": "^6.4.3"（^ は維持されるため、今後のマイナー／パッチアップグレードも引き続き可能です）。

自動バンプ設定とすべてのフラグについては、references/commands.md を参照してください。

アプリケーションのみ：ライブラリでは composer bump（--dev-only なし）を実行しないでください。下流の利用者に支障をきたす形で制約が狭まります。