こんにちは。テックリードの私だ。
日々のPHPアプリケーション開発において、Composerはもはや空気のような存在だ。`composer require` でパッケージをインストールし、何気なく `composer.json` をコミットする。小規模なプロジェクトであればそれだけで回るだろう。
しかし、ドメイン駆動設計を導入した大規模モノリスや、社内共通のマイクロサービス群、さらにはオープンソースのライブラリ開発に踏み込んだ瞬間、dependency hell（依存関係の地獄）の足音が近づいてくる。
「あるパッケージを入れたら、別の必須パッケージのバージョンが衝突してインストールできない」
「公式ライブラリに致命的なバグがあるため、一時的にフォーク版に差し替えたいが、他の依存関係がそれを許してくれない」
こうした現場の絶望をスマートに解決し、依存関係の汚染を未然に防ぐための強力な武器が、`composer.json` における `conflict` と `replace` だ。
今回は、単なるマニュアルの解説ではない。Composerの依存関係解決エンジン（SATsolver）の内部挙動を踏まえ、チームの生産性を極限まで高めるための「メタデータ設計の極意」を伝授しよう。
—
1. 依存関係解決エンジンの裏側と「汚染」のメカニズム
Composerが裏で何をしているか、意識したことはあるだろうか？
Composerは、指定された制約を満たすパッケージの組み合わせを数学的に解く（SAT問題として処理する）。このとき、開発者が適切な「境界線」を引いていないと、以下のような悪夢が起きる。
1. バージョンの乖離による致命的なバグ: 間接的な依存（ transitive dependency ）の先で、脆弱性のある古いライブラリが引っ張られてくる。
2. 名前空間の衝突: 同じクラス名や関数名を持つ異なるパッケージが同時にロードされ、予期せぬ挙動を引き起こす。
3. フォーク地獄: ベンダーの修正を待てずに自社でフォーク（Fork）した際、元のパッケージを指している他のサードパーティ製ライブラリがそれを認識できず、二重にコードが読み込まれる。
これらを防ぐために存在するのが `conflict` と `replace` だ。それぞれの設計思想と、実務での正確な使い分けを見ていこう。
—
2. `conflict`: 「共存不可」を宣言し、システムを護る防壁
`conflict` フィールドは、「このパッケージは、指定されたパッケージの特定のバージョンと同時に存在してはならない」ことをComposerに強制する宣言だ。
なぜ `conflict` が必要なのか？
「依存関係（`require`）」がポジティブな結合だとすれば、「競合（`conflict`）」はネガティブな結合、つまりシステムの安全装置である。
例えば、あなたが開発しているフレームワーク拡張パッケージが、あるロギングライブラリの `v1.x` 系とは完全に互換性がないAPIを持っているとする。もしユーザーが `v1.x` を入れたままあなたのパッケージを入れようとした場合、実行時エラーの海に放り込まれることになる。
`conflict` を使えば、Composerのインストール／アップデートのフェーズで「この組み合わせは不可能である」と早期に検知し、ビルドを安全に失敗させることができる。
実践的な `composer.json` のベストプラクティス構成例
以下は、厳格な型安全性とバージョン整合性を担保するライブラリの `composer.json` の一例だ。
{
“name”: “acme/enterprise-core”,
“description”: “エンタープライズ向けコアパッケージ：依存関係の厳格な制御”,
“type”: “library”,
“license”: “proprietary”,
“require”: {
“php”: “^8.2”,
“psr/log”: “^3.0”,
“symfony/http-foundation”: “^6.4 || ^7.0”
},
“require-dev”: {
“phpunit/phpunit”: “^10.5”
},
“conflict”: {
// セキュリティ上の脆弱性（CVE-XXXX-YYYY）が確認された特定のバージョンを排除
“vulnerable/logger-lib”: “<1.2.4",
// 自パッケージの内部アーキテクチャと致命的なコンフリクトを起こすレガシーパッケージをブロック
"legacy/framework-bridge": "",
// 互換性のない特定ベンダーのフォーク版の混入を物理的に阻止
"symfony/http-foundation": "7.1.0"
},
"config": {
"sort-packages": true,
"allow-plugins": {
"composer/installers": true
}
}
}
ここがプロのポイント
- 脆弱性バージョンのピンポイントブロック: まだパッチが当てられていない古い依存パッケージを `conflict` で弾くことで、CI/CDパイプラインの段階でセキュリティインシデントを未然に防げる。
- 完全排除 (“): アーキテクチャ上、絶対に同居させてはいけないパッケージがある場合、バージョンに “ を指定して完全に排除の意思を示す。
—
3. `replace`: 「すり替え」の美学とフォークパッケージのスマートな管理
次に `replace` だ。これが最も誤解されやすく、同時に最も強力な機能である。
`replace` フィールドは、「このパッケージは、指定された他のパッケージのコードを内包（または置換）しているため、他のパッケージを実際にインストールする必要はないとみなす」という宣言だ。
`replace` が圧倒的な威力を発揮するユースケース
1. オープンソースのフォーク（独自改修）:
サードパーティ製ライブラリ（例: `author/package`）に致命的なバグがあり、PRもマージされないため、自社で `acme/package` としてフォークして修正を入れた。しかし、プロジェクト内の他の依存ライブラリが依然として `author/package` を要求している場合、そのままでは両方がインストールされてしまう。ここで `replace` を使う。
2. モノリスのコンポーネント分割:
巨大なモノリシックアプリケーションを複数の内部パッケージに分割していく過渡期において、一時的にコードの所在をごまかすために使う。
実践的な `composer.json` のベストプラクティス構成例
公式の `monolog/monolog` に独自パッチを当てた社内用フォーク `acme/monolog` を作成し、プロジェクト全体で元のMonologの代わりにこれを強制適用する場合の設定だ。
{
“name”: “acme/monolog-fork”,
“description”: “社内要件を満たすためにセキュリティとパフォーマンスを最適化したMonologのフォーク版”,
type”: “library”,
“require”: {
“php”: “^8.2”
},
// ここが肝：元のパッケージを「自分が置き換える」と宣言する
“replace”: {
“monolog/monolog”: “self.version”
},
“autoload”: {
“psr-4”: {
“Monolog\\”: “src/”
}
}
}
この `acme/monolog-fork` をプロジェクトに組み込むと、Composerはこう判断する。
> 「お、どこかのパッケージが `monolog/monolog` を要求しているな。しかし、すでに `acme/monolog-fork` がロードされており、そいつが `monolog/monolog` を `replace` しているから、元の `monolog/monolog` をダウンロードしてくる必要はないな。よし、このフォーク版で依存関係を満たそう」
結果として、コードの重複やクラス名の衝突（Fatal Error: Cannot redeclare class…）を完璧に回避できるのだ。
—
4. プロの現場で実践する：チーム全体の生産性を底上げするルールとテクニック
ここからは、これらのメタデータを日々の開発に組み込み、チーム全体の開発スピードを劇的に高めるための実践テクニックを共有しよう。
神プラグイン＆CLIショートカット
手動で `composer.json` を書き換えて `composer update` を回すのは時間の無駄だ。以下のツールと設定を導入せよ。
1. `composer/pcre` や `hirak/prestissimo`（※Composer 2以降はコアに並列ダウンロードが統合済み）の活用
Composer 2.xの並列ダウンローダーを最大限活かすため、環境変数や設定を最適化する。
2. `composer validate` のCI/CD強制組み込み
`conflict` や `replace` を多用すると、JSONの構文ミスやバージョン制約の矛盾が起きやすくなる。必ずコミットフック（Husky等）やGitHub Actionsで以下を走らせる。
依存関係の構文および検証を厳格に行う
composer validate –strict –no-check-lock
チーム開発における共有化ルール
- `composer.lock` は正義、だがメタデータの変更時は例外なしで全員同期:
`conflict` や `replace` を変更した際、ロックファイルが古いままのメンバーがいると、環境によってビルドが通る・通らないという「私のローカルでは動くのに現象」の温床になる。
- フォーク利用時は必ず `replace` の理由をコメント（またはREADME）に残す:
なぜ公式パッケージをそのまま使わず `replace` しているのか。その理由（「本家PR #123のバグ修正がマージされるまでの暫定対応」など）をコードの文脈として残すことが、保守性を担保する鍵となる。
—
5. トラブルシューティング：依存関係解決で迷宮に入り込んだときのコマンド
もしあなたが `conflict` や `replace` を導入した結果、Composerが「Could not resolve dependencies」と泣き叫び始めたら、以下のコマンドで内部のグラフを視覚化せよ。
なぜそのパッケージがインストールできないのか、競合の原因ツリーを可視化する
composer why-not monolog/monolog 2.0
現在の依存関係のロック状態を無視して、競合解決のパスをデバッグ出力する
composer update –verbose –dry-run
これらのコマンドで、どのパッケージがどの `conflict` に引っかかっているのか、あるいは `replace` のバージョン制約がどこでミスマッチを起こしているのかが手に取るようにわかるはずだ。
—
結びにかえて
`conflict` と `replace` は、単なるComposerの高度なオプションではない。それは、「あなたのコードベースが、外部の混沌としたエコシステムとどう対峙するか」を定義するアーキテクチャの境界線である。
この境界線を適切にデザインできるようになれば、もはや「バージョン依存の地獄」に怯える必要はない。自信を持って複雑なパッケージエコシステムを統御し、チームの生産性を次のステージへと引き上げてほしい。