PHP 8.x時代を生き抜く：ComposerとマルチPHP環境を極めるアーキテクチャ設計
テックリードの役割とは、個人のコーディング速度を上げることではなく、「チーム全体の開発フィードバックループを極限まで高速化し、環境差異による不具合を物理的に排除する仕組み」を構築することにある。
現代のPHP開発において、レガシーなPHP 8.0から最新のPHP 8.3/8.4が混在するマルチPHP環境、あるいはローカルとCI/CD、本番サーバーの間でPHPバージョンが微妙に異なる状況は日常茶飯事だ。ここで多くのチームが陥るのが、「ローカルのPHPバージョンに合わせて依存関係が固定され、デプロイ先やCIでバージョン競合エラー（Your requirements could not be resolved to an installable set of packages）が爆発する」という悪夢である。
今回は、Composerの内部メカニズム（依存解決アルゴリズムとプラットフォームエミュレーション）を深く理解し、Dockerを駆使したマルチPHP環境において、依存関係の競合を完全に無効化するプロフェッショナルな設計術を伝授する。
—
1. 根源的理解：なぜComposerの「platform設定」がマルチPHP環境の救世主なのか？
Composerの依存解決の裏側
Composerは、`composer.json` に記載された `require` セクションを読み込み、Packagistからパッケージのメタデータを取得して、数学的なSAT（満たし可能性）問題として依存関係を解決する。この時、Composerは「現在実行されているPHPのバージョンと、有効な拡張機能（ext-）」を暗黙の基準として使用する。
もし、開発者のローカルマシンが PHP 8.3 であり、本番環境が PHP 8.1 である場合、ローカルで `composer update` を実行すると、PHP 8.3特有の機能や型定義に依存したパッケージのバージョンが選択されてしまい、PHP 8.1の本番環境で致命的なパースエラー（Fatal Error）を引き起こす。
逆に、古いPHP環境で実行すると、最新のPHP 8.x対応パッケージの恩恵を受けられない。
`config.platform` による仮想化
この問題を解決するのが、`composer.json` における `config.platform` 設定である。これは、「実際の実行環境のPHPバージョンや拡張機能を無視し、指定した仮想的なバージョン環境で依存関係を解決・ロックする」ための機能だ。
これにより、ローカルのPHPが何であれ、CIや本番環境と完全に同一のパッケージツリーを強制的に生成できる。
—
2. 実践：マルチPHP環境を完全制御する `composer.json` ベストプラクティス
チーム開発において、ローカル開発環境（Dockerなど）とCI/CDパイプラインの間で依存関係の矛盾を一切発生させないための、プロダクション品質の `composer.json` 設定例を提示する。
{
“name”: “enterprise/core-application”,
“description”: “High-performance enterprise backend system with multi-PHP compatibility.”,
“type”: “project”,
“license”: “proprietary”,
“require”: {
“php”: “^8.1 || ^8.2 || ^8.3”,
“ext-ctype”: “”,
“ext-iconv”: “”,
“ext-json”: “”,
“ext-mbstring”: “”,
“ext-pdo”: “”
},
“require-dev”: {
“phpunit/phpunit”: “^10.0”,
“friendsofphp/php-cs-fixer”: “^3.0”
},
“config”: {
“optimize-autoloader”: true,
“preferred-install”: “dist”,
“sort-packages”: true,
“platform”: {
“php”: “8.1.28”
}
},
“minimum-stability”: “stable”,
“prefer-stable”: true,
“scripts”: {
“post-autoload-dump”: [
“Illuminate\\Foundation\\ComposerScripts::postAutoloadDump”
]
}
}
この設定がもたらすアーキテクチャ上のメリット
1. `config.platform.php` の固定: 開発者がローカルにPHP 8.3を入れていようとも、Composerはこのプロジェクトのベースラインを PHP 8.1.28 として依存解決を行う。これにより、PHP 8.1でサポート外となるパッケージバージョンが誤ってインストールされるリスクをゼロにする。
2. `require` での柔軟性: 一方で、`require.php` 自体は `^8.1 || ^8.2 || ^8.3` と幅を持たせることで、将来的なアップグレードパスを塞がない。
3. `sort-packages: true`: 複数人での開発時に、`composer.json` の依存関係リストがアルファベット順に自動ソートされるため、Gitのコンフリクト（マージ競合）が劇的に減少する。
—
3. Docker連携術：ホスト環境を汚さずにマルチPHPを切り替える
Docker環境で開発を行う際、ありがちなミスが「ホストOS（Mac/Linux）のComposerバイナリをそのまま使ってコンテナ内のベンダーディレクトリを操作する」ことだ。これにより、ホストとコンテナのPHP拡張機能の差異（例: ホストに `ext-redis` がなく、コンテナにはある等）でComposerがエラーを起こす。
鉄則：Composerは必ず対象のPHPバージョンを持つDockerコンテナ内で実行する。
以下は、Docker Composeを用いたマルチPHP切り替え環境における、極めて実用的なシェルスクリプト（`bin/composer`）のラッパー実装である。
!/usr/bin/env bash
==============================================================================
Composer Docker Wrapper Script
ホスト環境のPHPバージョンに依存せず、Dockerコンテナ内のPHP/Composerを実行する
==============================================================================
set -euo pipefail
使用するDockerサービスの指定（例: php-81, php-82, php-83）
環境変数 PHP_SERVICE が未定義の場合はデフォルトで php-82 を使用
PHP_SERVICE=”${PHP_SERVICE:-php-82}”
実行中のプロジェクトルートディレクトリを取得
ROOT_DIR=”$(cd “$(dirname “${BASH_SOURCE[0]}”)/..” && pwd)”
ユーザー権限の整合性を保つため、ホストのUID/GIDをコンテナに渡して実行
exec docker-compose run –rm \
-u “$(id -u):$(id -g)” \
-v “${ROOT_DIR}:/app” \
-w /app \
“${PHP_SERVICE}” \
composer “$@”
使い方と恩恵
開発者はローカルにPHPをインストールする必要すらない。切り替えは環境変数を変えるだけだ。
PHP 8.1環境としてComposerコマンドを実行
PHP_SERVICE=php-81 ./bin/composer install
通常の依存関係更新（内部のPHP 8.2環境でプラットフォーム設定に基づき解決）
./bin/composer update
このアプローチにより、開発者のマシン環境差異に起因する「動かない地獄」から完全に解放される。
—
4. チームの生産性を加速する：神プラグインとキーボードショートカット
プロフェッショナルなエンジニアは、CLIのタイピング速度や無駄な操作を徹底的に排除する。
絶対に入れるべきComposerプラグイン
チーム全員のPCに導入を義務付けるべきデファクトスタンダード・プラグイン。
1. `oomphf/composer-installers-extender`
- 標準の `composer-installers` では対応しきれない複雑なサードパーティ製ライブラリの配置先（Custom Installer Paths）を完璧に制御する。特に大規模なモジュラーモノリスやCMS連携で必須。
2. `ergebnis/composer-normalize`
- `composer.json` のフォーマットとキーの順序を標準化する。コミット前に自動実行させることで、コードレビュー時の無駄なフォーマット指摘を完全になくす。
- 導入コマンド: `composer require –dev ergebnis/composer-normalize`
開発スピードを最大化するCLIテクニック
ターミナルでのComposer操作を爆速にするためのシェルエイリアス（`.zshrc` や `.bashrc` に記述）。
よく使うComposer操作のショートカット
alias c=”composer”
alias ci=”composer install”
alias cu=”composer update”
alias cr=”composer require”
alias crd=”composer require –dev”
alias c-dump=”composer dump-autoload -o”
alias c-check=”composer audit” # セキュリティ脆弱性スキャン
特に `composer audit`（PHP 8.2以降のComposer標準機能）は、依存しているパッケージに既知のCVE（脆弱性）がないかをPackagistのデータベースと照合して一瞬で検知する。CIのパイプラインの最初、あるいはコミットフック（Husky等）に組み込むことで、セキュリティインシデントを未然に防ぐ防壁となる。
—
5. テックリードが仕込むべきチーム共有ルール（まとめ）
マルチPHP環境とComposer運用を組織に定着させるためには、コードだけでなく「ルールと自動化の仕組み」をリポジトリに埋め込む必要がある。
1. `composer.lock` は必ずGitで管理する（アプリケーション開発の場合）。ライブラリ開発でない限り、チーム全員が1bitの狂いもなく同一の依存ツリーを使用することを強制する。
2. CI/CDでの厳格なプラットフォーム検証
GitHub ActionsなどのCI環境でも、コンテナのPHPバージョンと `composer.json` の `config.platform` が一致していることをテストフェーズの前提条件とする。
GitHub Actions のワークフロー断片例
- name: Validate Composer Config & Platform
run: |
docker-compose run –rm php-81 composer validate –strict
docker-compose run –rm php-81 composer check-platform-reqs
`composer check-platform-reqs` は、現在の実行環境（またはplatformで指定した環境）が、要求されているパッケージのPHPバージョンや拡張機能の要件を満たしているかを厳密に検証するコマンドである。これをCIに組み込むことで、デプロイ後の本番環境エラーを100%事前に防ぐことができる。
ツールの仕様をハックし、環境差異という不確実性をエンジニアリングでねじ伏せること。それこそが、現場を圧倒的なスピードへと導くテックリードの仕事である。