こんにちは！開発環境アーキテクトの私です。
毎日のコーディング、本当にお疲れ様です。
ふと、こんな経験はありませんか？
「自分のローカル開発環境では最新のPHP 8.3を入れてバリバリ開発しているのに、いざ本番サーバー（古いホスティング環境など）にデプロイしたら、なぜか`composer install`でエラーが出る」
あるいは、「ローカルではうまく動いたのに、本番環境で急に致命的なエラー（Fatal Error）が起きて冷や汗をかいた……」
これ、Web開発の現場で本当によくある「環境の罠」なんです。
今回は、この頭の痛い問題を一発で解決し、あなたの開発ライフを劇的に楽にしてくれる秘伝のレシピ――Composerの`platform`設定について、世界最高峰のアーキテクト視点から優しく、そして深く解説していきます。
これをマスターすれば、ローカルと本番のPHPバージョンの違いに怯える必要はもう二度となくなりますよ。さあ、一緒に扉を開けましょう！
—
なぜ「ローカルと本番のPHPバージョン乖離」は地獄を生むのか？
まずは、背後で何が起きているのかという「仕組み」を少しだけ覗いてみましょう。
Composerは、私たちが`composer.json`に書いた依存関係（ライブラリ）を解決する際、「今、コマンドを実行している環境のPHPバージョン」を基準にします。
- あなたのローカル環境: PHP 8.3
- 本番サーバー: PHP 8.1
この状態でローカルにて`composer require`などを実行すると、Composerはこう判断します。
> 「おっ、この開発者はPHP 8.3を使っているな！ じゃあ、PHP 8.3の最新機能に最適化されたライブラリのバージョンをインストールして、`composer.lock`に書き込んでおこう！」
しかし、この`composer.lock`をそのまま本番サーバー（PHP 8.1）に持って行って`composer install`を走らせるとどうなるでしょうか？
本番サーバーのPHP 8.1にとって、インストールされたライブラリが「PHP 8.2以降の機能」や「新しい構文」を使っていた場合、容赦なくエラーを吐いて沈黙します。
「じゃあ、ローカルも本番に合わせて古いPHPを使えばいいのでは？」
……いいえ、それはエンジニアとしての生産性を自ら捨てるようなものです。私たちは最新の快適な環境で開発したい。
ここで登場するのが、今回主役である Composerの`platform`設定 です。
—
基礎のセットアップ：`platform`設定とは何か？
`platform`設定とは、一言で言うと「Composerに対して、私の環境のPHPバージョンや拡張機能の有無を『嘘をついて』偽装させる機能」です。
これにより、ローカル環境がPHP 8.3であっても、「いや、我が家の本番環境はPHP 8.1.22なんだ」とComposerに思い込ませることができます。その結果、Composerは本番環境に完全一致したライブラリの組み合わせを、ローカルの最新環境で計算・生成してくれるのです。
基本の `composer.json` 設定例
実際のプロジェクトルートにある `composer.json` を開いてみてください。`config` セクションの中に `platform` を定義します。
{
“name”: “my-project/webapp”,
“description”: “PHPのバージョン乖離を制する堅牢なアプリケーション”,
“type”: “project”,
“require”: {
“php”: “^8.1”,
“monolog/monolog”: “^3.0”
},
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true,
/ ==========================================================
- ここから下が、本番環境のスペックを模倣する「platform」設定です
- ========================================================== /
“platform”: {
“php”: “8.1.22”
// ↑ ローカルが何であろうと、PHP 8.1.22であるとして依存関係を解決させます
}
}
}
この設定を行うことで、Composerは内部の依存関係ソルバーに対し、「このシステムにはPHP 8.1.22しか入っていない」と認識させます。そのため、PHP 8.2や8.3特有の依存関係を持つパッケージが誤って選定されるリスクを完全にシャットアウトできるのです。
—
精度高い動作確認：擬似環境で依存関係をコントロールする
では、実際にこの設定がどのように機能するのか、実践的なステップで確認してみましょう。
ステップ1: 現在の環境情報を確認する
まずは、あなたの手元の環境で次のコマンドを叩いてみてください。
php -v
(例: PHP 8.3.4 が動いていると仮定します)
ステップ2: あえて古いバージョンを `platform` に指定する
先ほど紹介したように、`composer.json` の `config` に `platform` を追記します。今回は少し厳密に、本番で使われていると仮定して `8.1.15` を指定してみましょう。
“config”: {
“platform”: {
“php”: “8.1.15”
}
}
ステップ3: 依存関係を再構築（クリーンインストール）する
設定を反映させるために、一度ロックファイルとベンダーディレクトリをリフレッシュし、インストールを実行します。
既存のロックファイルとベンダーフォルダをクリア（念のため）
rm -rf composer.lock vendor/
プラットフォーム設定を意識してインストールを実行
composer install
【ここで裏で何が起きているか？】
Composerは、ローカルで動いている本物のPHP 8.3を無視し、「PHP 8.1.15」という仮想的な制約のなかでベストなパッケージを選びに行きます。
ステップ4: 動作確認とログのチェック
インストールが完了したら、本当に想定通りのバージョンで解決されたかを確認します。
composer check-platform-reqs
このコマンドを実行すると、現在インストールされているパッケージが、指定したプラットフォーム要件（今回はPHP 8.1.15）に完全に適合しているかをチェックし、次のような美しいレポートを返してくれます。
> composer check-platform-reqs
Definingations:
php 8.1.15 success (matches 8.1.15)
ext-json 8.3.4 success (platformhas)
ext-mbstring 8.3.4 success (platformhas)
もし、ここで本番環境には入っていない（しかしローカルには入っている）拡張機能などに依存するパッケージを選んでしまっていた場合、ここで赤字のエラーとして検知できます。本番デプロイする前にローカルでバグを潰せる――これこそがアーキテクトが推奨するモダンな開発フローです。
—
現場で役立つプロの知見：PHPだけでなく「拡張機能」も固定せよ
実は、`platform`設定の真価はPHPのバージョン偽装だけにとどまりません。本番環境のPHP拡張機能（ext-）の有無まで完全にコントロールしてこそ、真のプロフェッショナルです。
例えば、ローカル環境には `ext-imagick` や `ext-redis` が入っていても、軽量な本番サーバー（コンテナなど）にはそれが入っていない場合があります。そんな時は以下のように記述します。
“config”: {
“platform”: {
“php”: “8.1.22”,
“ext-redis”: “5.3.7”,
“ext-imagick”: “3.7.0”
// 本番サーバーにインストールされている拡張機能のバージョンを明示的に固定
},
“platform-check”: true
// ↑【超重要】本番デプロイ時に、実行環境のPHP/拡張機能がこの要件を満たしているか強制チェックする
}
ここで注目していただきたいのが `”platform-check”: true` です。
これを有効にしておくと、本番環境でアプリケーションが起動した瞬間、もしPHPのバージョンや拡張機能が足りていなければ、アプリケーションが動く前に安全にクラッシュ（例外をスロー）してくれます。中途半端な状態で動いて謎のデータ破損を引き起こす最悪のシナリオを、未然に防いでくれるのです。
—
まとめ
いかがでしたでしょうか？
今回は、Composerの `platform` 設定を活用して、開発環境と本番環境のPHPバージョンの乖離を華麗に制御する方法を解説しました。
- ローカルと本番のバージョンの違いによる「デプロイ時の絶望」を防げる
- チーム開発やCI/CDパイプラインにおいて、環境依存のバグをゼロに近づけられる
- `platform-check` と組み合わせることで、本番の安全性劇的に向上する
「たった数行のJSONを書くだけ」で、これほどまでの安心感と開発効率を手に入れることができます。
これをマスターしたあなたなら、明日からのデプロイはもうビクビクすることなく、コーヒーを飲みながら優雅に行えるはずです。
毎日のコーディングが、もっと楽しく、もっとスマートになりますように。
それでは、次のアーキテクチャ解説でお会いしましょう！