こんにちは！開発現場を支えるインフラやツールの裏側を整えるのが大好きな、君の身近な先輩エンジニアです。
今日は、PHPの開発現場で避けて通れないComposer、そしてその中でも中〜大規模開発で必ずぶつかる「Repository Priority（リポジトリの優先順位設定）」についてお話しします。
「社内で作った共通ライブラリをComposerで導入したいけれど、なぜか公開版の古いパッケージが勝手に読み込まれてバグる……」
「セキュリティ的に信頼できないパッケージが混ざるリスクを根絶したい」
そんな現場の絶望をスマートに解決し、毎日のコーディングを劇的に安心・快適にするテクニックを、基礎から優しく丁寧に解説していきますね。これをマスターすれば、パッケージ管理のモヤモヤが一気に晴れますよ！
—
そもそもComposerとは？なぜ「優先順位」で悩むのか
PHPのプロジェクトを進める上で、今やComposerなしの生活は考えられません。Composerの本質は、単なるライブラリのダウンローダーではなく、「複雑に絡み合う依存関係のグラフを数理的に解決するエンジン」です。
デフォルトの挙動に潜む「魔物」
何も設定していない状態の `composer.json` は、世界中のオープンソースが集まる公式レジストリ Packagist.org を向いています。
ここで、企業が独自に開発した社内用パッケージ（例えば、認証基盤モジュールなど）をプライベートリポジトリ（Satis、Private Packagist、あるいはGitLabのパッケージレジストリなど）経由で導入し始めると、事件が起きます。
1. あなたが `composer require company/auth-package` を実行する。
2. Composerはデフォルトで「世界中のPackagist」と「社内レジストリ」の両方を探しに行く。
3. もし社内パッケージと同名のオープンソースパッケージがPackagistに存在していたり、バージョン解決のアルゴリズムの気まぐれ（あるいはキャッシュの古さ）によって、意図しない外部のパッケージがダウンロードされてしまう。
これは、悪意ある第三者がPackagistに同名パッケージを登録した場合、社内システムが乗っ取られる（Dependency Confusion攻撃）という致命的なセキュリティリスクに直結します。
だからこそ、「どのリポジトリを優先し、どれを遮断すべきか」を私たちが明示的にコントロールする必要があるのです。
—
基礎セットアップ：安全なリポジトリ環境の作り方
それでは、理論はこれくらいにして、実際に安全なリポジトリの優先順位を設定した `composer.json` の書き方を見ていきましょう。
今回は、「社内製パッケージは社内レジストリからのみ取得し、それ以外の一般的なライブラリは公式Packagistから取得する。さらに、公式Packagistからの不正な同名パッケージの混入を完全にシャットアウトする」という、実務で最も堅牢とされる設定を構築します。
実践的な composer.json の全体像
以下の設定ファイルをプロジェクトのルートに配置してください。各行の意味をコメントで詳しく解説しています。
{
“name”: “my-company/super-web-app”,
“description”: “セキュアな依存関係管理を施したPHPアプリケーション”,
“type”: “project”,
“require”: {
“php”: “^8.2”,
“my-company/auth-package”: “^1.0”,
“monolog/monolog”: “^3.0”
},
“repositories”: [
{
“type”: “composer”,
“url”: “https://packagist.example.com”,
“options”: {
“ssl”: {
“verify_peer”: true
}
}
},
{
“packagist.org”: false
}
],
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true
}
}
この設定のキモを徹底解説
1. `”packagist.org”: false` の魔法
- この1行が今回の主役です。あえて公式のPackagistを「無効（false）」に明示的に設定しています。
- 「えっ、じゃあ世の中の便利なライブラリ（Monologなど）はどうやってインストールするの？」と思いますよね。そこで登場するのが、直上のカスタムリポジトリURLです。ここでは社内専用のミラーサーバーやPrivate PackagistのURL（例：`https://packagist.example.com`）を指定しています。
- この社内サーバー側で「自社パッケージ」と「必要なパブリックパッケージ（Packagistのプロキシ）」を安全に一元管理・フィルタリングさせることで、開発者のローカルPCから直接パブリックなPackagistを見に行かない「ゼロ・トラストな依存関係解決」を実現できます。
2. 依存関係の順序と除外の力
- Composer 2.2以降、リポジトリの定義順序や除外設定の解釈が非常に厳密になりました。
- 上記のようにグローバルなPackagistを完全に断つアプローチのほか、特定のプレフィックスを持つパッケージ（例: `my-company/`）だけを社内リポジトリに強制し、それ以外は公式に逃がすという「パススルー型」の制御も可能です。
—
Hello World 的動作確認：意図通りに動いているか検証する
設定が完了したら、本当に意図した通りの挙動をしているか、コマンドラインから検証してみましょう。
ここでの動作確認は、単に「エラーが出ないこと」を確認するだけでなく、「どこからパッケージがダウンロードされているか」の足跡を追うことが重要です。
ステップ1：キャッシュのクリアとクリーンインストール
古いメタデータやキャッシュが残っていると正しい検証ができないため、一度綺麗に掃除します。
Composerのキャッシュを完全にクリアする（汚染された依存関係データの排除）
composer clear-cache
既存のロックファイルとベンダーディレクトリを削除してスクラッチ状態にする
rm -rf composer.lock vendor/
ステップ2：詳細なデバッグログ付きでインストールを実行
`-v`（verbose）オプションをつけて実行すると、Composerがどのリポジトリに問い合わせてパッケージを探しているのかが手に取るようにわかります。
デバッグ出力を有効にして依存関係の解決プロセスを覗き見る
composer install -vvv
実行ログの読み方（成功時のイメージ）：
Reading ./composer.json
Loading config file ./composer.json
Executing command (CWD): git rev-parse –is-inside-work-tree
Dependency resolution completed.
[2.4MB/0.1s] Importing symfony/polyfill-mbstring (v1.28.0) from https://packagist.example.com/…
[3.1MB/0.2s] Importing my-company/auth-package (v1.2.0) from https://packagist.example.com/…
ログの中に `https://packagist.org` への直接の通信や、予期せぬ外部URLからのダウンロードが一切混ざっていなければ、Dependency Confusion対策は大成功です！
—
先輩からのアドバイス：さらに現場を強固にするために
ここまで読み進めた君なら、もうComposerの裏側の動きがかなり見えてきているはずです。最後に、実務でさらに一歩進んだ環境を作るためのアドバイスを贈ります。
- チーム全員の環境を統一する
`composer.json` に記述したリポジトリ設定は、Gitなどのバージョン管理システムに必ず含めてチームメンバー全員で共有してください。誰か一人のローカル設定が狂っていると、CI/CDパイプライン（GitHub ActionsやGitLab CIなど）で突然ビルドが落ちる原因になります。
- CI/CD環境での `–no-interaction` との組み合わせ
自動化サーバーの上で動かす際は、必ず `composer install –no-dev –optimize-autoloader –no-interaction` を使い、対話入力を防ぎつつ、セキュアで高速なビルドを維持しましょう。
リポジトリの優先順位を正しく理解しコントロールできるようになると、セキュリティ事故を防げるだけでなく、「自分たちのコードベースを自分たちの手で完全に支配している」という心地よいエンジニアリングの自信につながります。
日々のコーディングが、より安全で、より楽しいものになりますように。
それでは、次の開発も一緒に頑張っていきましょう！