はじめに：なぜ大規模PHPプロジェクトのComposerは「地獄」と化すのか
テックリードとして多くのレガシー・モダン混在PHPプロジェクトを渡り歩いてきた私だが、チームメンバーから最も頻繁に持ち込まれる悲鳴の一つがこれだ。
> 「なんか `composer update` したら原因不明のコンフリクトが起きて進まなくなったんですけど……」
PSR-4のオートローディングや美しいアーキテクチャ設計の話をしている最中に、突然 `Your requirements could not be resolved to an installable set of packages.` という冷酷なエラーメッセージが画面を赤く染め上げる。そして、パニックに陥った開発者がやりがちな最悪の悪手がこれだ。
`rm -rf vendor composer.lock && composer install`
あるいは、場当たり的に `composer.json` のバージョン制約を “ や `^` に緩め、挙句の果てにCI/CDパイプラインを盛大にブローさせる――。
君たちはそろそろ、この「依存関係の闇鍋」を勘でデバッグするのをやめなければならない。Composerは決して黒魔術ではない。厳密な数学的グラフ理論に基づいたパッケージマネージャーである。その内部構造と正しいデバッグコマンドを理解すれば、どんなに複雑に絡み合った依存関係の糸も、一瞬で解きほぐすことができる。
今回は、数あるComposerの機能の中でも、大規模開発の現場で「知っているか否かでエンジニアの生存率が10倍変わる」二大神コマンド、`composer why` と `composer why-not` の極意を、私の実戦経験を交えて徹底的に伝授しよう。
—
1. 内部構造を理解する：Composerが裏側で行っていること
なぜ依存関係地獄は発生するのか。それを知るには、Composerが裏で何をしているかを知る必要がある。
Composerは、あなたが `composer.json` に記述した要件（Requirements）を読み込み、背後でSAT（充足可能性問題）ソルバーを走らせている。各パッケージが要求するバージョン制約（Constraint）を満たすような依存グラフ（Dependency Graph）の組み合わせを総当たり、あるいは最適化アルゴリズムで計算し、唯一解（または許容解）を導き出して `composer.lock` に書き込む。
ここで問題になるのは、プロジェクトが巨大化し、サードパーティ製ライブラリ（例えばLaravelのエコシステムや、AWS SDK、各種Guzzleプラグインなど）が増大すればするほど、「推移的依存（Transitive Dependencies：孫依存）」の網の目が複雑化することだ。
- あなたのコードが直接要求しているパッケージ：直接依存（Direct Dependency）
- ライブラリが内部で要求しているパッケージ：間接依存（Indirect Dependency）
「なぜか古くて脆弱性のあるパッケージが勝手にインストールされている」「あるライブラリをアップデートしたいのに、別の何かがそれをブロックしている」。この原因の8割は、間接依存の網のどこかでバージョン制約がコンフリクトしていることにある。
この迷宮の可視化とデバッグにおいて、GUIツールや勘に頼る必要はない。Composer標準装備のレーダー探知機、`why` と `why-not` があれば十分だ。
—
2. 犯人を特定するレーダー：`composer why` の実戦活用
ある日、プロジェクトの監査ツールから「`guzzlehttp/guzzle` の古いバージョンが使われている、直ちにバージョンを上げろ」という警告が出たとしよう。しかし、あなたの `composer.json` には直接 `guzzlehttp/guzzle` は書かれていない。
ここで最初に使うべきコマンドが `composer why`（エイリアスとして `composer depends` も利用可能）だ。
基本構文と実践ログ
$ composer why guzzlehttp/guzzle
このコマンドを実行すると、以下のような出力が得られる。
aws/aws-sdk-php 3.281.0 requires guzzlehttp/guzzle (^6.5.8 || ^7.0.1)
league/flysystem-aws-s3-v3 3.15.0 requires league/aws-s3-v3 (~3.20) -> depends on guzzlehttp/guzzle
【プロの着眼点】
出力結果から、直接の犯人（あるいは共犯者）が `aws/aws-sdk-php` や `league/flysystem-aws-s3-v3` であることが一発で判明した。
「なぜそのパッケージが存在しているのか」という問いに対し、`why` は依存関係の「上流（親）」を逆引きで教えてくれる。
さらに、特定のパッケージがどのパスで繋がっているかを深掘りしたい場合は、ツリー構造を意識しながら上位のパッケージに対しても `why` を連鎖させていくことで、プロジェクト全体の依存関係の血統書が頭の中で完全に構築される。
—
3. 衝突の壁を打ち破る：`composer why-not` による矛盾の特定
本丸はここからだ。バージョンをアップグレードしようとした際によく遭遇する、あの悪名高いエラーを考えてみよう。
`Composer could not resolve the version constraint: package x requires y 2.0, but you are locked at 1.0`
この「何が・なぜ・どのバージョンを拒絶しているのか」を数学的に一刀両断するのが `composer why-not` だ。
実践シナリオ：パッケージをアップグレードしたいのにできないとき
例えば、PHPのバージョンを8.2から8.3へ引き上げるために、ベースとなるフレームワークや主要パッケージを一斉にアップデートしようとしたところ、以下のようなコンフリクトが発生したとする。
$ composer why-not php 8.3.0
このコマンドは、「なぜ我がプロジェクト（あるいは特定のパッケージ）は、指定したバージョン（PHP 8.3.0）を受け入れることができないのか？」を逆引きで調査するコマンドである。
出力例を見てみよう。
psr/log 2.0.0 requires php >=8.0
monolog/monolog 2.9.2 requires php >=7.2 || ^8.0
my-company/legacy-sdk 1.2.0 requires php ~8.1.0 <- [犯人発見]
【解説】
`my-company/legacy-sdk` が内部で `php ~8.1.0` という厳格な制約（セマンティックバージョニングの罠）を持っているため、PHP 8.3環境への移行がブロックされていることが一目瞭然でわかる。
このように、`why-not` は「特定のバージョンに上げたい／下げたい」という目的に対し、どのパッケージのどの制約（Constraint）が足かせになっているかをピンポイントで暴き出すための最強のメスなのだ。
—
4. 開発スピードを劇的に高めるチートシート：知る人ぞ知るTips
ここからは、日々の開発やCI/CDパイプラインの構築において、シニアエンジニアがこっそり使っている実用的なテクニックと設定のベストプラクティスを共有しよう。
隠れたキーボードショートカット＆CLIテクニック
1. インタラクティブな検索を組み合わせる（zsh/fzf連携）
巨大な `composer.lock` から手動でパッケージ名を探すのは時間の無駄だ。`fzf` などのファジーファインダーと組み合わせ、シェル関数として `.zshrc` に登録しておこう。
# 依存関係をインタラクティブに逆引きするカスタムコマンド
cwhy() {
local pkg=$(composer show –name-only | fzf –prompt=”Select package to inspect: “)
[ -n “$pkg” ] && composer why “$pkg”
}
この関数を叩けば、プロジェクト内の全パッケージから対象をインタラクティブに選択し、即座に `why` の結果を表示できる。
2. `–tree` オプションの併用
`composer why` には直接的なツリー表示オプションはないが、`composer depends –tree` を使うことで、依存の階層構造を視覚的にレンダリングできる。
$ composer depends –tree vendor/package-name
—
5. チーム開発の生産性を極限まで高める `composer.json` ベストプラクティス
属人性を排し、チームメンバー全員が「依存関係地獄」に陥らないための堅牢な `composer.json` の設定例を提示する。
以下のJSONは、エンタープライズ品質のプロジェクトで実際に私が採用している構成だ。各行の意図をコメントとして読み取ってほしい。
{
“name”: “my-company/high-performance-app”,
“description”: “Enterprise-grade PHP backend service”,
“type”: “project”,
“license”: “proprietary”,
“require”: {
“php”: “^8.2”,
“ext-pdo”: “”,
“ext-mbstring”: “”,
“laravel/framework”: “^10.0”,
“guzzlehttp/guzzle”: “^7.5”
},
“require-dev”: {
“fakerphp/faker”: “^1.9.1”,
“mockery/mockery”: “^1.4.4”,
“nunomaduro/collision”: “^7.0”,
“phpunit/phpunit”: “^10.0”,
“spatie/laravel-ignition”: “^2.0”
},
“autoload”: {
“psr-4”: {
“App\\”: “app/”,
“Database\\Factories\\”: “database/factories/”,
“Database\\Seeders\\”: “database/seeders/”
}
},
“autoload-dev”: {
“psr-4”: {
“Tests\\”: “tests/”
}
},
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true,
“allow-plugins”: {
“pestphp/pest-plugin”: true,
“phpstan/extension-installer”: true
}
},
“minimum-stability”: “stable”,
“prefer-stable”: true,
“scripts”: {
“post-autoload-dump”: [
“Illuminate\\Foundation\\ComposerScripts::postAutoloaddump”
],
“post-update-cmd”: [
“@php artisan package:discover –ansi”
],
“debug:why”: “composer why”,
“debug:whynot”: “composer why-not”
}
}
押さえておくべき設定のポイント
- `”sort-packages”: true`
これが地味ながらチーム開発で最も重要な設定の一つ。`composer require` や `composer update` を行った際、`composer.json` 内のパッケージ名がアルファベット順に自動ソートされる。これにより、複数人による同時開発時のマージコンフリクト（Git Conflict）の発生率を劇的に低下させることができる。
- `”allow-plugins”` の明示的ホワイトリスト化
Composer 2.2以降、悪意のあるプラグインの実行を防ぐためにプラグインの自動実行が制限されている。チーム全体でセキュリティポリシーを統一し、許可するプラグインをここに明記することで、環境差異によるビルドエラーを未然に防ぐ。
- `”scripts”` セクションへのカスタムデバッグコマンド登録
`composer run debug:why` のように、プロジェクト固有のショートカットを生やすことで、メンバーがコマンドの構文を忘れるのを防ぐ。
—
6. まとめ：依存関係地獄をロジカルに制する者こそ、真のPHPアーキテクト
依存関係のコンフリクトに直面したとき、焦ってファイルを削除したり、適当にバージョンを書き換えたりする行為は、プロのエンジニアとしてもっとも避けるべき「技術的負債のばら撒き」である。
今回の要点を振り返ろう。
1. ComposerはSATソルバーのエンジンである：闇雲に触らず、背後のグラフ構造を意識する。
2. `composer why` で「上流の親」を炙り出す：なぜそのパッケージが存在するのかを逆引きする。
3. `composer why-not` で「衝突の壁」を特定する：バージョンアップの障害となっている足かせを数学的に突き止める。
4. `sort-packages` やカスタムスクリプトを活用し、チーム全体で防衛体制を敷く。
これらのツールと概念を血肉化すれば、どれほど巨大で複雑怪奇なレガシー依存関係を抱えたプロジェクトであっても、冷静かつ最短の時間で健全な状態へとリファクタリングすることができるはずだ。
明日からの君たちのコードレビュー、そしてトラブルシューティングのスピードが劇的に変わることを期待している。