こんにちは、テックリードの私だ。
日々のPHP開発で、`composer install` や `composer update` の実行が終わるのをぼーっと待っている時間は、エンジニアにとって最も生産性の低い無駄な時間だ。特に、Dockerを用いたコンテナ開発環境や、GitHub ActionsなどのCI/CDパイプラインにおいて、毎回リモートのPackagistやGitHubから数メガバイト、時には数ギガバイトものアーカイブをダウンロード・展開していれば、ビルド時間はみるみる膨れ上がり、チーム全体の開発ループの速度（Velocity）は大きく低下する。
今回は、Composerが内部でどのようにキャッシュを管理しているかという「メカニズムの根幹」を紐解き、DockerとCI/CD環境におけるグローバルキャッシュの永続化戦略、そして実務で即座に導入できるベストプラクティス構成を余すところなく伝授しよう。
ネットの海を漂う「なんとなくコピペした設定」から脱却し、パッケージ管理のオーバーヘッドを極限までゼロに近づけるアーキテクチャを手に入れてほしい。
—
1. Composerキャッシュの裏側：内部構造とデータフロー
まず、Composerがどのようにキャッシュをハンドリングしているのか、その内部構造を正確に把握する必要がある。
Composerは、キャッシュを主に2つのレイヤーに分けて管理している。これらはデフォルトではユーザーのホームディレクトリ（Linux/macOSなら `~/.cache/composer` または `~/.composer`、Windowsなら `%LOCALAPPDATA%\Composer`）に配置される。
① アーカイブキャッシュ（`cache/files`）
`composer require` や `composer install` 実行時、ComposerはリモートリポジトリからZIPやTARなどのアーカイブファイル（dist）をダウンロードする。
この時、ダウンロードしたアーカイブファイルそのものがハッシュ名をキーとして `cache/files` ディレクトリに保存される。
- メリット: 次回同じバージョンを要求された場合、ネットワークを一切使わず、ローカルのアーカイブから直接展開される。
② リポジトリメタデータキャッシュ（`cache/repo` と `cache/provider`）
Packagist APIから取得した `composer.json` のメタデータや、どのパッケージがどのバージョンを持っているかという依存関係のツリー情報がJSON形式でキャッシュされる。
- メリット: 依存関係解決（Dependency Resolution）の計算フェーズにおいて、リモートへHTTPリクエストを飛ばすオーバーヘッドを完全に排除する。
[Composer 実行]
│
├─> 1. メタデータ取得 ──> [cache/repo] (ローカルにあればHTTP通信スキップ)
│
├─> 2. 依存関係解決 ──> (メモリ上で高速に処理)
│
├─> 3. アーカイブ取得 ──> [cache/files] (ローカルにあればダウンロードスキップ)
│
└─> 4. ベンダー展開 ──> vendor/ ディレクトリへ出力
この内部構造から導き出される結論は一つだ。「`cache/files` と `cache/repo` を環境間でいかに共有・永続化するか」が、ビルド高速化の鍵を握る。
—
2. Dockerコンテナ環境におけるグローバルキャッシュの最適化
多くの開発現場で見かけるアンチパターンが、Dockerfile内で以下のように書いてしまうことだ。
【アンチパターン】これではビルドごとにキャッシュが破棄される
COPY . /var/www/html
RUN composer install –no-dev –optimize-autoloader
これでは、Dockerイメージのレイヤーが新しくなるたびにキャッシュが消え、コンテナを再ビルドするたびにフルダウンロードが発生する。
これを解決するためには、Dockerのビルドキャッシュ（BuildKit）の機能と、Composerのグローバルキャッシュディレクトリをマウントする戦略を組み合わせる。
実践的な Dockerfile 構成例
以下は、マルチステージビルドとBuildKitのキャッシュマウント (`–mount=type=cache`) を駆使した、極限まで最適化された `Dockerfile` のベストプラクティスだ。
syntax=docker/dockerfile:1.4
↑ BuildKitの高度なキャッシュ機能を使用するために必須のディレクティブ
FROM php:8.3-cli-alpine AS builder
1. システムに必要な依存関係とComposerのインストール
RUN apk add –no-cache git unzip libzip-dev
COPY –from=composer:2.7 /usr/bin/composer /usr/bin/composer
WORKDIR /app
2. 依存関係の定義ファイルのみを先にコピー（レイヤーキャッシュのヒット率を最大化）
COPY composer.json composer.lock ./
3. BuildKitのキャッシュマウントを使用してcomposer installを実行
コンテナ内の /root/.composer/cache をホスト側のBuildKitキャッシュストアにバインドする
RUN –mount=type=cache,target=/root/.composer/cache,sharing=locked \
composer install \
–no-dev \
–no-interaction \
–no-progress \
–no-scripts \
–prefer-dist
4. アプリケーションのソースコードをコピー
COPY . .
5. スクリプトの実行や最終的なオートローダーの最適化
RUN composer dump-autoload –no-dev –optimize-autoloader
本番用イメージの構築
FROM php:8.3-fpm-alpine
WORKDIR /var/www/html
COPY –from=builder /app /var/www/html
EXPOSE 9000
CMD [“php-fpm”]
この構成の技術的優位性
- `–mount=type=cache,target=/root/.composer/cache,sharing=locked`: コンテナが破棄されても、ホストのBuildKitストレージにComposerのアーカイブキャッシュが安全に保持される。`sharing=locked` を指定することで、並列ビルド時の競合（ファイルロックの衝突）を防ぎ、データの破損を完全に防止する。
- `composer.json` と `composer.lock` をソースコード本体より先に `COPY` している点：これにより、ソースコード（PHPファイルなど）が1行変更されただけでは `composer install` のレイヤーが再実行されず、ロックファイルに変更がない限り、一瞬でキャッシュから依存関係が復元される。
—
3. CI/CD環境（GitHub Actions）でのキャッシュ永続化戦略
GitHub ActionsなどのCIサーバーでも事情は同じだ。毎回クリーンな仮想環境が立ち上がるため、キャッシュを明示的に永続化させなければ毎回フルスクラッチのビルドとなり、CIの実行時間が無駄に浪費される。
ここで投入すべき神アクションが `shivammathur/setup-php` だ。このアクションは、PHPのセットアップだけでなく、Composerのキャッシュ管理を標準で内包している。
実践的な GitHub Actions ワークフロー設定（YAML）
以下に、実務で即座に採用できる堅牢なワークフローの構成例を示す。
name: Backend CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
# 1. リポジトリのチェックアウト
- name: Checkout code
uses: actions/checkout@v4
# 2. PHPとComposerのセットアップ（自動キャッシュ機能付き）
- name: Setup PHP & Composer
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.3’
tools: composer:v2
# デフォルトで composer.lock のハッシュをキーにして ~/.cache/composer をキャッシュしてくれる
env:
COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }} # API制限回避のためのGitHubトークン連携
# 3. Composerのキャッシュディレクトリパスをアクションから取得して確認（デバッグ用）
- name: Get Composer Cache Directory
id: composer-cache
run: |
echo “dir=$(composer config cache-files-dir)” >> $GITHUB_OUTPUT
# 4. 手動で厳密にキャッシュを制御したい場合のキャッシュアクション（オプション）
- name: Cache Composer dependencies
uses: actions/cache@v4
with:
path: ${{ steps.composer-cache.outputs.dir }}
# composer.lock のみをキーにして、ロックファイルが一致する場合のみキャッシュを復元
key: ${{ runner.os }}-composer-${–hash: hashFiles(‘/composer.lock’) }
restore-keys: |
${–runner.os}-composer-
# 5. 依存関係のインストール（キャッシュがヒットすればネットワーク通信はほぼゼロ）
- name: Install dependencies
run: composer install –no-progress –no-interaction –prefer-dist –optimize-autoloader
# 6. 静的解析やテストの実行
- name: Run Test Suite
run: vendor/bin/phpunit
CI高速化のプロフェッショナル・テクニック
- `COMPOSER_TOKEN` の設定: GitHub ActionsからPackagistやGitHub APIを大量に叩く際、未認証だとすぐにAPIレートリミット（Rate Limit）に引っかかり、ビルドが失敗する。GitHubのアクセストークンを環境変数として渡すことで、レートリミットの上限を引き上げ、安定したビルドを実現できる。
- `–prefer-dist` の徹底: ソースコードの履歴（Gitリポジトリ）を含まない軽量なアーカイブ（dist）を強制することで、ダウンロードサイズとディスクI/Oを最小限に抑える。
—
4. チーム開発における設定の共有化ルールとクリーンアップの注意点
グローバルキャッシュを共有・永続化する上で、チーム開発において避けて通れないのが「キャッシュの肥大化（Bloat）」と「破損（Corruption）」だ。
プロジェクトが長期化し、数多くのパッケージのバージョンアップを繰り返すと、`cache/files` の中には「二度と使われない古いバージョンのアーカイブ」が無限に蓄積され、数十ギガバイトに膨れ上がることがある。
キャッシュクリーンアップの正しい作法
不要になったキャッシュを削除するために、単に `rm -rf ~/.composer/cache` を実行するのは待ってほしい。やみくもに削除すると、現在アクティブな別プロジェクトのビルドで必要なキャッシュまで吹き飛ばし、一時的にビルド速度が低下する。
Composerには、安全に古いキャッシュをパージするためのビルトインコマンドが用意されている。
1. キャッシュディレクトリの現在の容量を確認する
composer clear-cache –ansi –dry-run
（※実際には削除せず、どれだけの容量がキャッシュされているかを確認できる）
2. アクセス日時が古いキャッシュファイルを自動でクリアする（例: 6ヶ月以上使われていないもの）
※Composer 2.2以降でサポートされているガベージコレクション的なアプローチ
find ~/.cache/composer/files -type f -mtime +180 -delete
チーム全体で強制すべき `composer.json` のベストプラクティス構成例
開発者個人のローカル環境やCI環境で、依存関係の解決方針にブレが生じないよう、プロジェクトの `composer.json` には以下の設定を必ず含めるべきだ。
{
“name”: “enterprise/core-service”,
“type”: “project”,
“description”: “High-performance backend service with optimized dependency management”,
“keywords”: [“framework”, “api”, “microservice”],
“license”: “proprietary”,
“require”: {
“php”: “^8.3”,
“laravel/framework”: “^11.0”,
“guzzlehttp/guzzle”: “^7.8”
},
“require-dev”: {
“phpunit/phpunit”: “^11.0”,
“larastan/larastan”: “^2.9”
},
“config”: {
/ オートローダーの最適化をデフォルトで有効化 /
“optimize-autoloader”: true,
/ クラスマップの厳格なホスティング（パフォーマンス向上） /
“classmap-authoritative”: true,
/ パッケージの安全性を担保するため、デフォルトで厳格なプラットフォーム要件チェック /
“platform-check”: true,
/ セキュリティ脆弱性のあるパッケージのインストールを警告・阻止する設定（Composer 2.x対応プラグイン等と連携） /
“preferred-install”: “dist”,
/ 並列ダウンロードの最適化（パラレル処理による高速化） /
“github-protocols”: [“https”]
},
“scripts”: {
/ チームメンバー全員が同じ手順でキャッシュをクリアしつつクリーンインストールできる共通コマンド /
“:refresh”: [
“composer clear-cache”,
“rm -rf vendor composer.lock”,
“composer install”
]
}
}
設定の極意
- `classmap-authoritative: true`: 本番環境やCIにおいて、ファイルシステムへの `file_exists` の問い合わせをゼロにする。PSR-4オートローディングの検索を完全にクラスマップ（静的な対応表）に固定化するため、アプリケーションの起動速度が劇的に向上する。
- `”scripts”: { “:refresh”: […] }`: チームメンバーが「なんか依存関係がおかしい」とハマった際に、個人の我流で適当なコマンドを叩かせるのではなく、プロジェクト標準のキャッシュクリア＆クリーンインストール手順をコードとしてリポジトリに担保する。これがチームの生産性を守るシールドとなる。
—
テックリードからの総括
Composerのキャッシュは、単なる「おまけの機能」ではない。インフラストラクチャの設計思想と直結した、ビルドパイプラインの生命線である。
- Docker環境では BuildKitのキャッシュマウント を用いてコンテナ外へ永続化する。
- CI/CD環境では ロックファイルのハッシュをキーにしたキャッシュ機構 で無駄なネットワークI/Oを駆逐する。
- プロジェクト設定では `classmap-authoritative` や適切なスクリプト定義 により、チーム全体の振る舞いを統一する。
これらの仕組みをコードとインフラの双方でデザインしきった時、あなたのチームの開発スピードは、他の追随を許さない圧倒的な領域へと到達するだろう。さあ、今すぐ手元の `Dockerfile` と `workflow.yml` を見直し、無駄な待機時間を過去のものにしてほしい。