こんにちは、テックリードの私だ。
日々のPHPアプリケーション開発において、こんな悪夢を経験したことはないだろうか？
「ローカル開発環境ではPHP 8.3をいち早く導入して快適にコード書いていたのに、いざ本番環境（PHP 8.1）にデプロイした瞬間、CI/CDパイプラインやステージングサーバーで謎の致命的エラー（Fatal Error）が爆発した」
あるいは、「古いPHPバージョンをサポートしているライブラリをインストールしたいだけなのに、Composerが『あなたのローカルのPHPは8.3だから、このパッケージの古いバージョンはインストールさせない』と頑なに拒否してきた」
この問題の本質は、「手元の開発環境のPHPランタイムバージョン」と「ターゲットとなる本番環境のPHPランタイムバージョン」の間に乖離があること、そしてデフォルトのComposerが「今動いているローカルのPHPバージョン」を正義として依存関係を計算してしまうことにある。
この構造的な爆弾を完全に無力化し、チーム全体のデプロイ安全性を劇的に高めるためのキー・コンポーネントが、`composer.json` の `config.platform` 設定だ。
今回は、Composerの内部挙動のメカニズムから、実務で即座に使えるベストプラクティス、そして開発効率を限界まで引き上げるプロの技まで、余すところなく伝授しよう。
—
1. なぜ `platform` 設定が必要なのか？（Composer内部のデータフロー）
まず、Composerがどのように依存関係を解決しているか、その内部の動きを解き明かそう。
Composerが `composer.lock` を生成、または更新するとき、以下の情報を照らし合わせる。
1. `composer.json` に記述されたパッケージの制約（例: `”php”: “>=8.1″`）
2. 現在実行されているPHPインタープリターのバージョン（例: ローカルの `/usr/bin/php` が返す `8.3.2`）
デフォルトの状態では、Composerは後者（現在のローカルPHPバージョン）を絶対的な環境制約として使用する。そのため、ローカルがPHP 8.3であれば、Composerは「PHP 8.3で動作確認された最新のパッケージ群」をロックファイルに書き込もうとする。
これを本番環境（PHP 8.1）に持って行ったとき、何が起きるか？
本番のPHP 8.1環境で `composer install` を実行した際、もしロックファイルに含まれる依存パッケージのどれかが「PHP 8.2以降の機能（新構文や内部関数の追加など）」をこっそり使っていた場合、本番でロードされた瞬間にアプリケーション全体がクラッシュする。
`platform` 設定の正体
`composer.json` の `config.platform` は、Composerに対して「おい、実際のローカルのPHPバージョンは無視しろ。俺たちが指定するこのバージョン（例: 8.1.25）で動いていると仮定して依存関係を計算しろ」と強制命令を下す機能だ。
これにより、ローカル環境がどんなに最新のPHPであっても、本番環境と完全に同一のバージョンをターゲットにした堅牢な `composer.lock` を生成・維持できるようになる。
—
2. 実践：`composer.json` のベストプラクティス構成例
百聞は一見にしかず。実際のプロジェクトで即座に採用すべき、洗練された `composer.json` の `config` セクションの構成例を見てほしい。
以下のJSONファイルは、単なる設定の羅列ではなく、ローカルと本番の乖離を防ぎつつ、開発者のストレスをゼロにするための工夫が詰まっている。
{
“name”: “enterprise/core-app”,
“description”: “High-performance enterprise backend application”,
“type”: “project”,
“require”: {
“php”: “^8.1”,
“ext-pdo”: “”,
“ext-mbstring”: “”,
“ext-openssl”: “”,
“laravel/framework”: “^10.0”
},
“require-dev”: {
“phpunit/phpunit”: “^10.0”,
“friendsofphp/php-cs-fixer”: “^3.0”
},
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true,
“allow-plugins”: {
“pestphp/pest-plugin”: true,
“phpstan/extension-installer”: true
},
“platform”: {
“php”: “8.1.22”
},
“platform-check”: true
}
}
設定値の深掘り解説
- `”platform”: { “php”: “8.1.22” }`
- ここが本記事の核心だ。開発者のローカル環境がPHP 8.3であっても、ComposerはこのプロジェクトのPHPバージョンは一貫して `8.1.22` であるとみなして解決処理を行う。これにより、本番環境と完全に同期した安全なロックファイルが生成される。
- `”platform-check”: true`
- Composer 2.1以降で導入された神機能。本番サーバーなどで `vendor/autoload.php` が読み込まれる際、「実際に動いているサーバーのPHPバージョン」と「`platform` でエミュレートしたバージョン」の整合性を自動チェックしてくれる。もし本番のPHPが古すぎて要件を満たしていない場合、意図しない挙動や致命的エラーを起こす前に、明確な例外をスローして安全に停止する。
- `”sort-packages”: true`
- `require` や `require-dev` のパッケージ名をアルファベット順に自動ソートする。複数メンバーによるGitのマージコンフリクトを劇的に減らすための必須設定。
—
3. チーム開発で事故らないための共有化ルール
`platform` 設定は非常に強力だが、チーム開発において運用ルールを誤ると、かえって混乱を招く。テックリードとして、以下のルールをチームに徹底してほしい。
ルール1: 本番環境の「パッチバージョン」まで正確に合わせる
`”8.1″` と大雑把に指定するのではなく、本番サーバー（またはAWS Elastic Beanstalk、Dockerコンテナなど）で実際に稼働しているPHPの正確なパッチバージョン（例: `8.1.22`）まで指定すること。マイナーバージョンの違いによる微妙な関数の挙動差や、バグフィックスの差異による事故を防ぐためだ。
ルール2: CI/CDパイプラインでの検証
GitHub ActionsやGitLab CIなどのパイプラインでは、実際に本番と同じPHPバージョン（例: `8.1.x`）のコンテナ上で `composer install` を走らせるべきだ。
その際、`platform` 設定が正しく機能していれば、ローカルのPHPバージョン（8.3等）に依存することなく、CI上でピタリとビルドが成功するはずである。
—
4. 開発効率を極限まで高めるプロの技（ショートカット & プラグイン）
ここからは、日々のComposer作業を極限まで高速化し、ストレスフリーな開発環境を実現するための実践知を授けよう。
A. ターミナル作業を加速するZsh/Bashエイリアス
Composerのコマンドは冗長だ。日常的に叩くコマンドは、以下のエイリアスを `~/.zshrc` や `~/.bashrc` に登録して指の反射で実行できるようにせよ。
依存関係の高速クリーンインストール（vendorとロックファイルを完全同期）
alias cci=’rm -rf vendor composer.lock && composer install’
プラットフォーム設定を無視して、現在のローカルPHPの限界まで上げてテストしたい時のコマンド
alias cupdate=’composer update –ignore-platform-reqs’
キャッシュをクリアして重い依存解決の沼から脱出する
alias ccc=’composer clear-cache’
B. 絶対入れるべき神プラグイン：`hirak/prestissimo` の思想を継承する現代の最適化
かつて並列ダウンロードで一世を風靡した `prestissimo` はComposer 2の標準機能にマージされ不要になったが、現在において入れるべきは `dealerdirect/phpcodesniffer-composer-installer` や `phpstan/extension-installer` といった、拡張機能の自動配線を担うプラグイン群だ。
特に、大規模なモノリスやマイクロサービス群を管理する場合、以下のコマンドでグローバルに並列処理や最適化の挙動を確認できるようにしておくこと。
Composer自体の並列処理能力を最大限に引き出す設定（環境変数）
export COMPOSER_PROCESS_TIMEOUT=2000
—
5. トラブルシューティング：どうしてもローカルの拡張機能と衝突する場合
`platform` 設定を導入すると、時々以下のようなエラーに遭遇することがある。
> Your requirements could not be resolved to an installable set of packages.
> … package xing/some-package requires ext-bcmath but no such extension is installed.
これは、「ComposerはPHPのバージョンを偽装しているが、ローカルのPHP環境にその拡張機能（例: `bcmath`）が入っていない」場合に発生する。
この問題をスマートに解決するには、`config.platform` の中で不足している拡張機能を明示的に「存在している」とモック（偽装）すればよい。
{
“config”: {
“platform”: {
“php”: “8.1.22”,
“ext-bcmath”: “8.1.22”,
“ext-gd”: “8.1.22”
}
}
}
このように記述することで、ローカルに特定のPHP拡張機能がインストールされていなくても、Composerは「その拡張機能は存在しているものとして」依存関係の解決を完遂してくれる。Docker環境や軽量なローカル環境で開発する際の手間を劇的に削減できるテクニックだ。
—
6. まとめ
開発環境と本番環境のバージョン乖離は、多くのチームが一度は踏む地雷だ。しかし、`composer.json` の `config.platform` を適切に設計・運用することで、このリスクを完全にコントロール下に置くことができる。
今日からあなたのプロジェクトの `composer.json` を見直し、本番環境と完全に同期した堅牢なプラットフォーム設定を導入してほしい。コードを書くことだけに集中できる、真にストレスフリーな開発環境がそこには待っている。