モノレポ管理の極意：Composer Workspacesによる依存関係の最適化
テックリードの皆さん、日々のPHP開発でこんな泥沼にハマったことはないだろうか？
「共通認証ライブラリを修正したのに、それをインポートしているAPIマイクロサービス側で反映を確認するためだけに、わざわざ `composer bump` をして、Gitにコミットし、Private Packagistへプッシュし、各サービスの `composer.json` を書き換えて `composer update` を叩く……」
このフィードバックループの遅さは、開発者の認知負荷を高め、タイポやバージョンの整合性エラーを誘発する最大のガンだ。特に、複数ドメインのバックエンドサービスやパッケージ群を一つのリポジトリで管理するモノレポ（Monorepo）構成において、パッケージマネージャーの立ち回りを誤ると、ビルド時間は増大し、依存関係の地獄が幕を開ける。
今回は、Composerの隠れた（あるいは見過ごされがちな）真骨頂である PathリポジトリとWorkspaces的運用 を極め、ローカルパッケージ間の参照をゼロレイテンシー化し、バージョン競合を完全制圧するための実践的アーキテクチャを伝授する。
—
1. なぜ「従来型のPackagist経由」はモノレポで破綻するのか？
多くのチームがモノレポへ移行した初期段階で犯す最大のミスは、各サブプロジェクト（例: `packages/auth`, `services/api`）を完全に独立したリポジトリとして扱い、Composerの通常のバージョン解決メカニズムに委ねることだ。
内部で何が起きているか？
Composerはデフォルトでリモート（またはローカルキャッシュ）のメタデータを参照し、SemVer（セマンティック・バージョン）の制約を満たすパッケージを探しに行く。たとえ同一リポジトリ内に最新コードが存在していいても、バージョン制約（例: `^1.2.0`）が一致しない、あるいはロックファイル (`composer.lock`) が更新されていなければ、古いコードが参照され続ける。
これを解決するのが、Composerの `path` リポジトリ型シンボリックリンク運用 である。
—
2. 究極のモノレポ構成：`composer.json` ベストプラクティス
モノレポのルートディレクトリに配置するマスターの `composer.json`、および各サブサービスの構成設計を見ていこう。
ポイントは、ルート側で `repositories` に `path` タイプを指定し、各サブプロジェクトの `composer.json` では、あたかも外部の公開パッケージであるかのようにシームレスにそれを要求することだ。
ルート `composer.json`（全体統括）
{
“name”: “enterprise/monorepo-core”,
“description”: “Enterprise PHP Monorepo Root Workspace”,
“type”: “project”,
“license”: “proprietary”,
“require”: {},
“require-dev”: {
“friendsofphp/php-cs-fixer”: “^3.0”,
“phpunit/phpunit”: “^10.0”
},
“repositories”: [
{
“type”: “path”,
“url”: “packages/”,
“options”: {
“symlink”: true
}
},
{
“type”: “path”,
“url”: “services/”,
“options”: {
“symlink”: true
}
}
],
“minimum-stability”: “dev”,
“prefer-stable”: true,
“config”: {
“sort-packages”: true,
“allow-plugins”: {
“pestphp/pest-plugin”: true
}
}
}
【アーキテククトの解説】
- `”type”: “path”` と `”url”: “packages/”` の組み合わせにより、ワイルドカード配下にあるすべてのディレクトリをローカルリポジトリとして自動認識させる。
- `”symlink”: true`（デフォルトでもtrueだが明示を推奨）により、コピーではなくシンボリックリンクとしてベンダーディレクトリ配下にマウントされる。これにより、`packages/auth/src/AuthManager.php` をエディタで保存した瞬間、`services/api/vendor/enterprise/auth/` から参照される実体コードも即座に更新される（ゼロ・ビルドタイムの達成）。
- `”minimum-stability”: “dev”` と `”prefer-stable”: true` の併用は、ローカルの不安定な開発版パッケージを許容しつつ、外部ライブラリについては安定版を優先する鉄壁の設定だ。
—
サブサービス側の設定例 (`services/api/composer.json`)
APIサービス側では、ルートで定義されたローカルパッケージを通常の依存関係として宣言する。
{
“name”: “enterprise/api-service”,
“description”: “Core API Service Backend”,
“type”: “project”,
“require”: {
“php”: “^8.2”,
“enterprise/auth-package”: “”,
“enterprise/shared-dto”: “^1.0”
},
“autoload”: {
“psr-4”: {
“App\\”: “src/”
}
},
“config”: {
“optimize-autoloader”: true,
preferred-install”: “dist”
}
}
—
3. 大規模開発におけるバージョン競合を回避するベストプラクティス
モノレポが成長するにつれて直面するのが、「サービスAは `auth-package` の `^1.0` を要求し、サービスBは `^2.0`（破壊的変更あり）を要求する」というバージョン競合問題だ。モノレポであっても、各サービスの依存関係が独立している場合、ロックファイルの競合やオートローダーの二重読み込みリスクが発生する。
これを防ぐためのプロフェッショナルな規律を挙げる。
A. 共通基盤パッケージは「常に最新の “（dev-main）」を許容する
モノレポ内のローカルパッケージ間においては、SemVerの束縛をあえて緩め、`””`, `”dev-main”`, または `”self.version”` を活用する。モノレポのメリットは「全コードが常に同期して動くこと」にあるため、古いバージョンのコードを温存する必要性自体がアーキテクチャのアンチパターンだ。
B. オートローダーの最適化とプレフィックス衝突の防止
複数のパッケージが同一のベンダー名（例: `Enterprise\`）を使う場合、PSR-4のネームスペース設計が重複すると、Composerのクラスマップ生成時に予期せぬ挙動を招く。
各パッケージの `composer.json` における `autoload` セクションは、厳格にディレクトリ構造と名前空間を一致させること。
{
“autoload”: {
“psr-4”: {
“Enterprise\\Auth\\”: “src/”
}
}
}
—
4. 開発効率を爆上げする CLI ＆ ワークフローの極意
ここからは、実務の現場でチームの生産性を限界突破させるためのコマンド術と、開発体験（DX）を最適化するプラクティスを紹介する。
1. シンボリックリンクの整合性を保つ `composer update` の作法
ローカルパスを変更した際や、新規にパッケージを追加した際は、毎回ルートで以下のコマンドを実行し、依存関係のグラフを再構築する。
ルートディレクトリから一括でシンボリックリンクとオートローダーを再生成
composer update –lock –no-scripts
`–lock` を付与することで、リモートのパッケージ取得によるネットワーク遅延を回避しつつ、ローカルパスの解決情報だけを高速に `composer.lock` に焼き付けることができる。
2. 開発体験（DX）を加速させるカスタムスクリプト
モノレポでは、各サブプロジェクトに潜ってテストや静的解析を実行するのは苦痛だ。ルートの `composer.json` に Monorepo全体のオーケストレーション・スクリプト を定義せよ。
ルートの `composer.json` に以下を追加する：
{
“scripts”: {
“test:all”: [
“@php vendor/bin/phpunit packages//tests services//tests”
],
“stan:all”: [
“vendor/bin/phpstan analyse packages/ services/ –level=max”
],
“mono:install-all”: [
“composer install”,
“cd services/api && composer install”,
“cd services/web && composer install”
]
}
}
これにより、開発者はルートでたった一行叩くだけで、全サブシステムのテストと静的解析をパスさせることができる。
全パッケージ・サービスの静態解析とテストをワンコマンドで実行
composer stan:all
composer test:all
—
5. チーム開発で絶対に共有すべき「神プラグイン」と設定ルール
CI/CDパイプラインやローカル環境の差異で事故を起こさないために、チーム全体で以下の設定を強制する。
1. 絶対に入れるべき神プラグイン: `wikimedia/composer-merge-plugin`
モノレポにおいて、各サブサービスの `composer.json` をルートから一元管理したい、あるいは開発用依存関係（PHPUnitやPHPStanなど）をルートに集約しつつ、各サービスの依存関係とマージしたい場合に必須となるプラグイン。
ルートの `composer.json` に以下を組み込む：
{
“require”: {
“wikimedia/composer-merge-plugin”: “^2.1”
},
“extra”: {
“merge-plugin”: {
“include”: [
“services//composer.json”,
“packages//composer.json”
],
“recurse”: true,
“replace”: false,
“ignore-duplicates”: false,
“merge-extra”: true
}
}
}
このプラグインが背後で何をやっているかというと、Composerの初期化プロセスにおいて、指定した複数ファイルの `require` や `autoload` 設定を動的にメモリ上で結合し、単一の巨大な依存関係ツリーとして解決してくれる。これにより、バラバラだったサービス群の依存関係矛盾をComposerが単一のスコープで検知できるようになる。
2. チームのCI/CDパイプラインでの最適プラクティス
CI環境（GitHub Actions等）では、シンボリックリンクの解決が正しく行われるように、キャッシュ戦略を構築する必要がある。
.github/workflows/monorepo-ci.yml の抜粋
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.2’
tools: composer:v2
- name: Get Composer Cache Directory
id: composer-cache
run: echo “dir=$(composer config cache-files-dir)” >> $github.output
- name: Cache Composer Dependencies
uses: actions/cache@v3
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: ${{ runner.os }}-composer-${{ hashFiles(‘/composer.lock’) }}
restore-keys: |
${{ runner.os }}-composer-
- name: Install Root & Workspace Dependencies
run: composer install –no-progress –prefer-dist –no-interaction
- name: Run Workspace Tests
run: composer test:all
—
テックリードとしての結び
Composer Workspaces（PathリポジトリとMerge Pluginの組み合わせ）をモノレポに導入することは、単なる「フォルダの整理整頓」ではない。それは、チームの開発スピードを何倍にも跳ね上げ、バージョン不整合という無駄なコンフリクトのストレスからエンジニアを解放するための極めて高度なインフラストラクチャ設計である。
今日からあなたのモノレポでも `type: path` と `composer-merge-plugin` を導入し、真にモダンでアジリティの高いPHP開発環境を構築してほしい。コードの変更が、ラグなく、ダイレクトに全サービスへ伝播する快感をチーム全員で体感できるはずだ。