こんにちは！日々のPHP開発、お疲れ様です。
皆さんは、大規模なLaravelやSymfonyなどのフレームワークを使ったプロジェクトで、サードパーティ製のライブラリを追加しようとした際、以下のような絶望的なエラーメッセージに直面したことはありませんか？
Your requirements could not be resolved to an installable set of packages.
Problem 1
- Root composer.json requires symfony/http-foundation 6.4. -> satisfiable by symfony/http-foundation[v6.4.0].
- some-vendor/legacy-package v1.2.0 requires symfony/http-foundation ^5.4 -> found symfony/http-foundation[v5.4.0, …, v5.4.x-dev] but these conflict with your requirements.
「あれ？俺はただ新しいライブラリを入れたいだけなのに、なぜか古いパッケージが邪魔をしている……？」「ていうか、この `some-vendor/legacy-package` って、そもそも誰が何のためにインストールしたんだっけ？」
プロジェクトが大きくなり、チーム開発の期間が長くなるにつれて、`composer.json` とその裏側にある巨大な依存関係ツリー（`composer.lock`）は、まるで複雑に絡み合ったジャングルのようになっていきます。
今回は、そんな「依存関係地獄」に迷い込んだとき、一筋の光となり、あなたを救い出すための強力な武器――`composer why` と `composer why-not` という2つのコマンドの活用法を、実務的なデバッグ手順と共にお伝えします。
これをマスターすれば、原因不明のパッケージ競合に頭を悩ませる時間はゼロになり、毎日のコーディングが劇的に楽になりますよ。ぜひ最後までお付き合いください！
—
1. そもそも Composer と依存関係管理の本質とは？
私たちが普段何気なく使っている Composer は、単なる「ライブラリのダウンローダー」ではありません。その本質は、「数学的なグラフ理論（Directed Acyclic Graph: 有向非巡回グラフ）に基づき、数千個に及ぶパッケージ間のバージョン制約を完璧に満たす単一の解を計算するエンジン」です。
プロジェクトのルートにある `composer.json` には「こうしたい」というあなたの願い（制約）が書かれ、`composer.lock` にはその計算結果（どのパッケージの、どのハッシュ値のバージョンをインストールするか）が固定されています。
しかし、次のような状況が発生したとき、Composerの計算エンジンは音を上げます。
- パッケージAはライブラリXの「バージョン2系」を要求している
- しかし、あなたが入れたいパッケージBは、ライブラリXの「バージョン1系」しかサポートしていない
この矛盾を解決するには、「なぜそのパッケージが入っているのか（犯人は誰か）」と、「なぜバージョンが上がらない・競合するのか（壁は何処にあるのか）」を正確に突き止める必要があります。ここで登場するのが `why` と `why-not` です。
—
2. 基礎知識：環境構築と動作確認（Hello World）
本題のデバッグコマンドに入る前に、大前提となる Composer の基本セットアップと、正しく環境が動いているかを確認する「Hello World」的なステップをおさらいしておきましょう。すでにComposerが動いている方は、次の章までスキップしていただいても構いません。
インストールと動作確認のステップ
Composerは公式インストーラーを使ってグローバルに配置するのが最も安全です。ターミナル（CLI）を開き、以下のコマンドを順に実行してください。
1. 公式インストーラーを一時ディレクトリへダウンロード
php -r “copy(‘https://getcomposer.org/installer’, ‘composer-setup.php’);”
2. インストーラーの整合性（SHA-384）を検証（セキュリティ対策）
php -r “if (hash_file(‘sha384’, ‘composer-setup.php’) === ‘dac65bcfc0fc4477eef8389537188d4048e1b488db532ff331be13a8f160961fb2138804375ae2f0221f5fd2975d315f’) { echo ‘Installer verified’; } else { echo ‘Installer corrupt’; unlink(‘composer-setup.php’); } echo PHP_EOL;”
3. composer.phar をシステム全体で使えるように ‘composer’ という名前で移動
sudo php composer-setup.php –install-dir=/usr/local/bin –filename=composer
4. インストーラーのクリーンアップ
php -r “unlink(‘composer-setup.php’);”
動作確認（Hello World）
正しくインストールされたか、バージョン情報を確認してみましょう。
composer –version
【期待される出力例】
Composer version 2.6.x 2023-XX-XX XX:XX:XX
このバージョン表示が確認できれば、準備完了です。Composerはあなたのプロジェクトを救う準備を万端に整えています。
—
3. 「なぜこのパッケージがあるのか？」を暴く `composer why`
最初に取り上げるのは `composer why` （エイリアスとして `uses` も使えます）です。
`composer why` の役割
あるパッケージが、直接的（`composer.json` に自分で書いた）なのか、あるいは間接的（別のパッケージが依存しているから、勝手に入ってきたトランジティブ依存）なのかを追跡し、依存関係のツリー構造を逆算して表示してくれます。
実践：不要なレガシーパッケージの足取りを追う
例えば、プロジェクト内に `monolog/monolog` というログ出力ライブラリが入っているとします。「自分はこんなログライブラリを直接指定した覚えはないぞ？」と思ったとき、こう打ちます。
composer why monolog/monolog
【実行結果のイメージ】
psr/log 1.1.4 requires monolog/monolog (^2.0)
symfony/error-handler v6.4.0 requires psr/log (^1.0 || ^2.0 || ^3.0)
laravel/framework v10.43.0 requires psr/log ^1.0 || ^2.0 || ^3.0
※注：環境によって出力形式や文言は多少異なります。
この出力結果をどう読み解くべきか？
下から上に向かって依存関係が連鎖しています。
1. `laravel/framework` が `psr/log` を要求している
2. `symfony/error-handler` も `psr/log` を要求している
3. 結果として `monolog/monolog` が引っ張られてきている、ということが一目瞭然で分かります。
このように、「誰がそのパッケージを必要としているのか（依存の親）」を突き止めることで、「このパッケージ、実は古い機能Aを消せば丸ごと削除できるのでは？」といった大胆なリファクタリングの判断が可能になります。
—
4. 「なぜインストールできないのか？」の矛盾を突く `composer why-not`
次が本日のハイライトです。パッケージをアップデートしようとしたり、新しいものを入れようとしたりしたときに発生する「依存関係地獄」を論理的にハックするのが `composer why-not` です。
`composer why-not` の役割
指定したパッケージの特定のバージョンが、なぜ現在のプロジェクト環境（または他のパッケージの制約によって）にインストールできないのか、その「拒絶理由」を明確にリストアップしてくれます。
実践：バージョン競合の犯人を特定するデバッグ手順
例えば、最新のPHP 8.2環境で、あるパッケージを `^3.0` にアップデートしようとしたところ、次のようなエラーで弾かれたとします。
composer why-not vendor/super-lib 3.0.0
頭の中で悩むのをやめ、このコマンドを叩いてみましょう。
【実行結果のイメージ】
Root composer.json – requires vendor/super-lib (^2.0)
some-vendor/old-plugin 1.5.0 requires vendor/super-lib (^2.1)
おお、なんと美しいログでしょうか！
「なぜ `vendor/super-lib` のバージョン 3.0.0 が入らないのか？」の答えがここにあります。
1. あなたの `composer.json` が `^2.0` を要求しているから（これは自分の手で `composer.json` を書き換えれば解決できます）
2. 最大の障害： `some-vendor/old-plugin` というプラグインが `vendor/super-lib (^2.1)` をハードコードして要求しているため、3.0系へジャンプすることがシステム上許されていない
つまり、「`vendor/super-lib` を 3.0 にしたければ、まず妨げとなっている `some-vendor/old-plugin` をアップデートするか、プロジェクトから外す必要がある」という次のアクションが論理的に導き出されるのです。
—
5. 現場で使える！依存関係トラブルシューティングの黄金フロー
実際の現場では、これら2つのコマンドを組み合わせて複合的なバグを撃退します。シニアエンジニアが実践しているトラブルシューティングのステップを公開しましょう。
[ステップ1: 競合のエラーに直面]
↓
[ステップ2: `composer why-not` で「壁」になっているパッケージを特定]
↓
[ステップ3: `composer why` でその「壁」の親をたどる]
↓
[ステップ4: 対策の決定（パッケージの更新、フォーク、コードの修正など）]
具体例：身動きが取れなくなったときのコマンドリファレンス
もし迷ったら、以下のコマンドを上から順にターミナルに流してみてください。状況が手に取るように見えてきます。
1. 競合しているパッケージの「入らない理由」を完全にスキャンする
composer why-not ターゲットのベンダー名/パッケージ名 バージョン番号
2. 邪魔をしているパッケージが、どこから引きずり出されたものか調査する
composer why 邪魔をしているパッケージ名
3. 依存関係のツリー全体を視覚的に俯瞰したい場合（全体像の把握）
composer depends –tree ターゲットのパッケージ名
特に最後の `composer depends –tree` は、巨大なツリー構造をテキストで美しく描画してくれるため、チームメンバーへSlack等で共有する際にも非常に重宝します。
—
6. まとめ
いかがでしたでしょうか？
今回は、Composerの影の主役とも言える `composer why` と `composer why-not` を使った、パッケージ競合の論理的なデバッグ手法について解説しました。
- `composer why
` で、そのパッケージを「誰が必要としているのか」を遡る。 - `composer why-not
`
これまで、エラーメッセージを適当に読み飛ばして `composer.json` や `composer.lock` を力技で直接書き換えたり、全削除して再インストール（`rm -rf vendor && composer install`）して時間を無駄にしていた日々に、今日で別れを告げましょう。
この2つのコマンドを手にすれば、どんなに複雑怪奇なレガシープロジェクトの依存関係であっても、恐れることなく冷静にメスを入れることができます。
あなたの開発ライフが、よりストレスフリーでクリエイティブなものになりますように。それでは、また次回の技術解説でお会いしましょう！