序：ローカルと本番の「バージョン乖離」という静かなる爆弾
開発者のローカル環境で動く最新のPHP 8.3。だが、安全第一で運用されている本番ステージングサーバーやAWS ECS上のコンテナはいまだPHP 8.1のまま。
この環境で何が起きるか？
あなたがローカルで `composer require` を実行した瞬間、Composerはあなたのローカル環境（PHP 8.3）のランタイム情報を正として依存関係を解決し、`composer.lock`を生成する。PHP 8.3特有の型定義や、8.1には存在しない関数・属性を前提としたパッケージの最新バージョンがロックファイルに書き込まれる。
そして、その `composer.lock` を抱えたままCI/CDパイプラインが回り、本番環境へデプロイされた瞬間にエラーが爆発する。
`Fatal error: Uncaught Error: Call to undefined function…` あるいは `Your requirements could not be resolved to an installable set of packages.` というCIの非情なレッドサイン。
この「バージョン乖離」は、単なるケアレスミスではない。Composerの内部アーキテクチャの本質を見誤っているがために発生する、構造的な人災である。
本稿では、Composerの `config.platform` 設定を軸に、この乖離を完全に根絶し、ローカル・CI・本番の三位一体で依存関係を完全に制御するための低レイヤアプローチと、現場で即座に導入できる実践的アーキテクチャを解説する。
—
1. Composer内部メカニズム：なぜ`platform`設定が必要なのか？
Composerの依存関係解決アルゴリズムと「環境依存性」
Composerは、`composer.json` と `composer.lock` を解決する際、デフォルトでは「現在コマンドを実行しているPHPランタイムの環境（PHP本体のバージョン、有効な拡張機能、Zend Engineのバージョン）」を自動検出し、その制約下で動作するパッケージの組合せを計算する。
[実行環境のPHP 8.3] ──> (Composerが自動検出) ──> platform.php = 8.3 とみなす
│
▼
【PHP 8.3専用のパッケージ群を選択】
│
▼
[composer.lock 生成]
この仕様は、開発者個人のマシンと本番サーバーのスペックが完全に一致している理想郷であれば問題ない。しかし、モダンな開発において、エンジニアは手元のMacBook（Apple Silicon）で最新のPHPを走り抜けさせ、本番は安定版のLinuxコンテナで運用するというのが現実だ。
ここに `config.platform` を導入することで、Composerに対し「実際の実行環境がどうであれ、指定した仮想的なプラットフォーム環境であるかのように振る舞え」と強制できる。
`platform` 設定がもたらす3つの巨大なメリット
1. 環境依存性の排除: 開発者のローカルPHPバージョンに関わらず、チーム全員およびCI環境で完全に同一の `composer.lock` が生成される。
2. 無駄なAPI通信と計算コストの削減: プラットフォーム要件を厳格化することで、Composer Resolverが探索するパッケージのバージョンツリーが絞り込まれ、依存関係解決のパフォーマンスが向上する。
3. デプロイメントの堅牢性: 本番環境のPHPバージョンに合わせたパッケージが確実に選択されるため、ランタイムエラーの確率が物理的にゼロになる。
—
2. 実践的アーキテクチャ：`composer.json` の高度な設計
実際のプロジェクトでどのように `config.platform` を組み込むべきか。単にPHPのバージョンを固定するだけでなく、PECL拡張機能のダミー化まで踏み込んだプロダクションクオリティの設定例を提示する。
究極の `composer.json` 設定例
{
“name”: “enterprise/core-backend”,
“description”: “High-performance enterprise microservice backend”,
“type”: “project”,
“require”: {
“php”: “^8.1”,
“ext-pdo”: “”,
“ext-mbstring”: “”,
“ext-redis”: “^5.0”
},
“require-dev”: {
“phpunit/phpunit”: “^10.0”
},
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true,
“platform”: {
“php”: “8.1.22”,
“ext-redis”: “5.3.7”
}
},
“minimum-stability”: “stable”,
“prefer-stable”: true
}
設定値の深掘り解説
- `config.platform.php: “8.1.22”`:
ローカルでPHP 8.3を使っていようとも、ComposerはこのプロジェクトのPHPバージョンは「8.1.22である」と厳密に解釈して依存関係を解決します。これにより、PHP 8.2以降の機能を利用したライブラリが誤って選定されるのを防ぎます。
- `config.platform.ext-redis: “5.3.7”`:
開発者のローカル環境にRedis拡張機能が入っていない、あるいはバージョンが異なる場合でも、指定したバージョンが存在するものとして処理を継続させることができます。これにより、「CI環境や特定の開発者のマシンに特定のPECL拡張が入っていない」という理由でビルドが失敗するデスマーチを防ぎます。
—
3. Dockerコンテナ環境 × Composer platform の完全自動構成
DevOpsの現場において、ローカル開発環境の標準化にはDockerが不可欠である。しかし、Dockerコンテナ内であっても、ホスト側の依存関係やバージョンミスマッチによる罠は存在する。ここでは、マルチステージビルドを活用し、`platform` 設定と完璧に調停されたコンテナ構築パイプラインの設計を示す。
Dockerfile（マルチステージ・プロダクションビルド）
=====================================================================
ステージ 1: ビルドステージ (Composerによる依存関係の解決と最適化)
=====================================================================
FROM composer:2.6 AS builder
WORKDIR /app
ソースコードをコンテナに転送
COPY composer.json composer.lock ./
【重要】ローカル/ビルド環境のPHPバージョン差異を完全に無視し、
本番環境(PHP 8.1)のプラットフォーム定義に基づいて依存関係を強制インストール
RUN composer install \
–no-dev \
–no-interaction \
–no-ansi \
–no-scripts \
–prefer-dist \
–optimize-autoloader
アプリケーションの全ソースコードをコピー
COPY . .
オートローダーの最適化を最終確定
RUN composer dump-autoload –no-dev –classmap-authoritative
=====================================================================
ステージ 2: ランタイムステージ (軽量かつセキュアな本番イメージ)
=====================================================================
FROM php:8.1-fpm-alpine AS runtime
WORKDIR /var/www/html
本番稼働に必要な最低限のシステムパッケージとPHP拡張をインストール
RUN apk add –no-cache \
libzip-png \
oniguruma-dev \
&& docker-php-ext-install pdo_mysql mbstring opcache
ビルドステージで生成された「最適化済みのベンダーディレクトリ」のみを抽出・コピー
COPY –from=builder /app/vendor /var/www/html/vendor
COPY –from=builder /app /var/www/html
セキュリティ強化: 権限の最小化
RUN chown -R www-data:www-data /var/www/html
USER www-data
EXPOSE 9000
CMD [“php-fpm”]
この設計により、Composerを実行するビルドコンテナのPHPバージョンが何であれ、`composer.json`の `platform` 設定とステージ1の挙動が連動し、本番環境（PHP 8.1）に完全最適化された `vendor/` が生成される。
—
4. CI/CDパイプラインとの高度な連携とバリデーション
「`composer.json` に `platform` を書き忘れた」「ローカルでうっかり `platform` なしでロックファイルを更新してしまった」。こうしたヒューマンエラーをCI/CDのゲートキーパーで完全に弾く仕組みを構築する。
GitHub Actionsワークフロー設定例
以下のCIワークフローは、コミットされた `composer.lock` が、プロジェクトが定義する `platform` 設定と完全に整合しているかを厳密に検証（Validate）する。
name: CI – Dependency & Platform Validation
on:
pull_request:
branches: [ main, develop ]
push:
branches: [ main, develop ]
jobs:
validate-composer:
name: Validate Composer Platform Consistency
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Setup PHP Environment
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.3’ # CIランタイム自体は最新を使用してもよい
tools: composer:v2
- name: Validate composer.json and composer.lock syntax
run: composer validate –strict
- name: Check if composer.lock is up to date with platform constraints
run: |
# 実際のインストールを行わず、ロックファイルがプラットフォーム要件を満たしているかドライラン検証
composer check-platform-reqs
`composer check-platform-reqs` の驚異的な効用
CI上で `composer check-platform-reqs` を走らせることで、現在の `composer.lock` がターゲットとするプラットフォーム（`config.platform`で定義されたバージョンや拡張機能）に対して、過不足がないかを瞬時に検証できる。もしローカルで誤って新しいPHP関数に依存したパッケージを入れてしまった場合、このステップが即座に検知し、ビルドを失敗させる。
—
5. 高度なハック：プラットフォーム偽装の限界と注意すべき罠
伝説的アーキテクチャを目指す者として、`config.platform` の「光」だけでなく「影（制約・アンチパターン）」も完全に把握しておかなければならない。
1. ネイティブC拡張機能のダミー化に伴うリスク
`config.platform.ext-redis: “5.3.7”` のように、実際にはマシンに入っていないPECL拡張を偽装した場合、Composerは「その拡張が存在するもの」としてパッケージのインストールを許可する。
しかし、アプリケーションの実行時（Runtime）に本当にその拡張がサーバーに入っていなければ、当然ながらクラッシュする。
> アーキテクトの金言: `platform` で偽装してよいのは「CIや開発時の依存解決プロセスを通過させるため」あるいは「本番サーバーには確実に入っているが、ローカルの軽量環境にはあえて入れていない拡張」に限定せよ。存在しない拡張を偽装してコード上でその関数を呼び出すのは、自ら時限爆弾を埋め込む行為に等しい。
2. `platform-check.php` の自動生成とその挙動
Composer 2.0以降、デフォルトで `vendor/composer/platform-check.php` が自動生成される。これは、アプリケーションのエントリーポイント（`autoload.php`）が読み込まれる際、実行中のPHPランタイムが `config.platform`（または最小PHP要件）を満たしているかをブートストラップ時に動的チェックする優秀な機構である。
もし本番サーバーのPHPバージョンが要件を満たしていなければ、データベースに接続する前にスクリプトが安全に停止（Exit）する。この挙動を無効化したい場合（特殊な環境変数のパッチを当てる場合など）以外は、`config.platform-check` を明示的に `false` にすべきではない。
{
“config”: {
“platform-check”: true
}
}
—
結：依存関係の主導権をエンジニアリングで奪還せよ
「ローカルでは動いたのに、本番で落ちた」——この開発現場の不条理なエンジニアリングストレスは、運や個人の注意深さで解決するものではない。それはツールの仕様を理解し、システム的に「乖離が発生し得ないパイプライン」を構築することでしか根絶できない。
`composer.json` の `config.platform` は、多様な開発環境の混沌を統制し、デプロイメントの再現性を極限まで高めるための強力な魔術である。
今すぐあなたのプロジェクトの `composer.json` を開き、本番のPHPバージョンを正確にプロットせよ。その瞬間から、あなたのバックエンド環境は、環境差異というランダムなノイズから完全に解放される。