はじめに：なぜ、あなたのComposerは「意図しないコード」を引くのか？
テックリードとして多くのPHPプロジェクトを監査していると、いまだに `composer.json` のリポジトリ定義を甘く見ている現場に遭遇する。
`”repositories”: [{ “type”: “packagist”, “url”: “https://packagist.org” }]` と何気なく書き、その下に社内Shatil（Satis）やPrivate Packagist、あるいはGitHubリポジトリを並べて安心していないだろうか？
Composerの依存関係解決エンジン（SATsolverアルゴリズムをベースにした依存関係ソルバー）は、デフォルトでは「見つかった中で最新のバージョン」を全リポジトリから横断的に探し出そうとする。この挙動は、パブリックなオープンソースを使う分には極めて強力だが、「社内専用の認証トークンを必要とするプライベートパッケージ」や「フォークして改修した独自のコアライブラリ」を扱う現場においては、致命的なセキュリティホールとビルド破壊の温床となる。
もし悪意ある第三者が、社内パッケージと全く同じベンダー名・パッケージ名のパッケージを本家 `packagist.org` に登録したらどうなるか？ 依存関係の解決順位制御（Repository Priority）を正しく行っていなければ、あなたのCI/CDパイプラインは秒速で汚染された外部パッケージをダウンロードし、本番環境へとデプロイしてしまうだろう。
本記事では、Composerの裏側で動く解決エンジンの挙動を解き明かし、Packagistと社内レジストリを安全・高速に混在させるための決定版リポジトリ優先順位戦略を、実務直結のコードとともに完全解説する。
—
1. Composer依存関係解決の深層：なぜ「上から順」に読まれないのか？
多くの開発者は、「`repositories` 配列の上部に書いたリポジトリが優先される」という致命的な誤解をしている。
Composerの内部アーキテクチャにおいて、`repositories` に定義された各リポジトリは、パッケージのメタデータを収集する「プロバイダ」として並列に扱われる。特定のパッケージ名（例: `acme/auth-sdk`）を解決する際、Composerは接続可能なすべてのリポジトリに対してそのパッケージが存在するか問い合わせる。
そして、デフォルトでは全リポジトリの中で最も新しいバージョンを持つものが選ばれる。
つまり、社内レジストリにある `acme/auth-sdk` のバージョンが `1.2.0` であったとき、もし誰かが悪意を持って（あるいは偶然同じ名前で）本家 `packagist.org` に `1.99.0` の同名パッケージを公開した場合、Composerは躊躇なく `packagist.org` 側の偽装パッケージを選択してしまう。これが「Dependency Confusion（依存関係混乱）」攻撃のメカニズムだ。
このリスクを根絶するためには、Composerが持つ `canonical`（標準）制御 と `packagist.org` の部分無効化（あるいは完全無効化） の仕組みをコードレベルで理解し、強制しなければならない。
—
2. 実践！セキュアかつ高速な `composer.json` ベストプラクティス構成
チーム開発の生産性を落とさず、かつセキュリティを極限まで高めた `composer.json` の実用的な設定例を提示する。
以下の設定では、
1. グローバルな `packagist.org` を完全に遮断、または必要最低限に制限する
2. 社内パッケージはプライベートレジストリ（Private Packagist等）からのみ取得させる
3. 特定のフォークライブラリはローカルパスまたは特定URLから強制する
という設計を具現化している。
{
“name”: “acme/enterprise-backend”,
“description”: “High-performance backend service with strict repository priority.”,
“type”: “project”,
“require”: {
“php”: “^8.2”,
“laravel/framework”: “^10.0”,
“acme/auth-sdk”: “^2.1”,
“acme/payment-gateway”: “^1.5”
},
“repositories”: [
{
“type”: “composer”,
“url”: “https://packages.private-packagist.com/com-acme/”
},
{
“packagist.org”: false
}
],
“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
}
コードの深掘り解説
- `”packagist.org”: false`
- ここが最大のキモである。 この一行によって、デフォルトのパブリックレジストリである `packagist.org` へのメタデータ問い合わせを完全に遮断する。これにより、前述した Dependency Confusion 攻撃を構造的に不可能にする。
- `”type”: “composer”, “url”: “https://packages.private-packagist.com/com-acme/”`
- 社内の認証済みプライベートレジストリを定義。パブリックなPackagistを無効化したため、すべての公開パッケージ（Laravelなど）の解決も、このプライベートレジストリを経由（プロキシ・キャッシュ経由）して安全に行われるようになる。
- `”sort-packages”: true`
- `composer require` 実行時に `require` および `require-dev` ブロック内のパッケージ名をアルファベット順に自動ソートする。Gitでのマージコンフリクトを劇的に減らすためのテックリード必須の定石設定。
—
3. シチュエーション別：高度な優先順位コントロール術
すべてのプロジェクトで `packagist.org: false` が使えるわけではない。「社内独自のプライベートパッケージを一部使いつつ、基本は通常のパブリックPackagistを使いたい」というハイブリッドな環境ではどうすべきか。
ここで登場するのが、特定のパッケージ名だけを社内リポジトリに強制する `exclude` / `only` 制御、あるいは 複数のリポジトリ間での厳密な優先順位づけ である。
パターンA：特定ベンダーのパッケージのみ社内レジストリを強制する
パブリックなPackagistを残しつつ、`acme/` から始まるパッケージは絶対に社内レジストリからしか引かせたくない場合、以下のようにリポジトリ定義を記述する。
“repositories”: [
{
“type”: “composer”,
“url”: “https://satis.internal.net”,
“only”: [“acme/”, “internal-libs/”]
},
{
“type”: “packagist.org”
}
]
- `only` キーの威力: この設定により、Composerは `acme/` および `internal-libs/` に一致するパッケージを探す際、他のリポジトリ（packagist.org等）を一切参照しなくなる。これにより、万が一パブリック側に同名パッケージが登録されても、検索対象から完全に除外されるため安全性が担保される。
—
4. 開発スピードを極限まで高めるCLIテクニック & 神プラグイン
アーキテクトとして、設定ファイルだけでなく、開発者の手元（Local Environment）のオペレーション速度も最大化させたい。日々の開発で導入すべきツールとコマンドを伝授する。
1. 絶対入れるべき神プラグイン: `hirak/prestissimo` の現代的後継と並列ダウンロード
かつては `hirak/prestissimo`（パラレルダウンローダー）が必須だったが、Composer 2.x系ではデフォルトでネイティブの並列ダウンロードが実装されている。
そのため、追加のプラグインを入れずとも、Composer 2を使用するだけでダウンロード速度は劇的に向上している。今すぐ全開発者のComposerを v2.x 以上にアップグレードさせよ。
`composer self-update`
2. 開発効率を爆上げするCLIショートカット (`composer.json` の `scripts` 活用)
チームメンバー全員が同じコマンドで品質チェックを行えるよう、`scripts` セクションにワークフローをコード化する。
“scripts”: {
“post-update-cmd”: [
“@php artisan optimize:clear”
],
“inspect”: [
“vendor/bin/phpstan analyse –memory-limit=2G”,
“vendor/bin/pest”
],
“rebuild”: [
“composer clear-cache”,
“composer install –prefer-dist”
]
}
- `composer inspect`: 静的解析（PHPStan）とテスト（Pest）をワンライナーで実行。CIが落ちる前にローカルで完全に検知できる。
- `composer rebuild`: 依存関係がおかしくなった（ロックファイルの不整合など）際、キャッシュクリアからクリーンインストールまでを安全に一撃で行う。
—
5. トラブルシューティング：リポジトリ優先順位で事故ったときの処方箋
現場でよくあるのが、「設定を変えたのに、なぜか古いキャッシュが残ってしまい新しい社内パッケージが反映されない」というトラブルだ。Composerは高度なキャッシュメカニズムを持っているため、以下のステップでデバッグを行え。
1. メタデータキャッシュの強制クリア
Composerは一度取得したパッケージのメタデータをローカルに強固にキャッシュする。設定を変更したら、まずこれを疑うべき。
composer clear-cache
2. どのリポジトリからパッケージが引かれているかの完全追跡
依存関係の解決過程を詳細にデバッグしたい場合は、`-v`（verbose）オプションを付けて実行する。
composer update acme/auth-sdk -v
出力ログの中に、どのURL（レジストリ）からパッケージの情報を取得しに行っているかが詳細に表示される。もしここで `packagist.org` から同名パッケージをフェッチしているログが見つかった場合、`repositories` の `exclude` や `only`、あるいは `”packagist.org”: false` の設定が正しく効いていない証拠である。
—
おわりに：規律あるリポジトリ管理が、強靭なプロダクトを生む
「動けばいい」という甘い認識で組まれた `composer.json` は、成長するチームの足取りを必ず重くする。そして最悪の場合、サプライチェーン攻撃の踏み台となり、企業に取り返しのつかない損害を与える。
今回解説した `packagist.org` の適切な制御、`only` によるスコープ制限、そしてComposer 2の特性を活かした設計は、モダンなPHP開発において「あって当たり前の防壁」である。
今すぐあなたのプロジェクトの `composer.json` を開き、リポジトリの優先順位がセキュアに保たれているか確認してほしい。その小さな行数が、あなたのチームのプロダクトを未来永劫守る盾となる。