こんにちは！日々の開発、本当にお疲れ様です。
皆さんは、新しいPHPのプロジェクトを立ち上げる時や、チームメンバーが `composer install` を叩いた直後、こんな面倒な作業に直面したことはありませんか？
「あ、先に `.env.example` をコピーして `.env` を作って、アプリケーションキーの生成コマンドを叩いて、パーミッションを設定して……っと、あれ？これ毎回手動でやるの面倒くさいな……」
開発の初期段階や、オンボーディング（新しいメンバーがチームに参加すること）のたびに発生するこの手作業、実は人間の記憶や手間に頼るべきではありません。なぜなら、人間は必ず「あ、`.env` のコピー忘れた！」というミスを犯すからです。
今回は、世界中のPHPプロジェクトでデファクトスタンダードとなっているパッケージマネージャー「Composer」のPlugin APIを使い、ライブラリのインストールやアップデートなどのイベントを華麗にフックして、環境設定ファイル（`.env.example` から `.env`）の自動生成・コピーを行う仕組みを徹底解説します。
これをマスターすれば、`composer install` を実行した瞬間に、あなたのプロジェクトが必要な初期セットアップを勝手に完了させてくれるようになります。毎日のコーディング前の儀式を自動化し、開発体験（DX）を劇的に向上させましょう！
—
1. なぜComposerの「スクリプト」ではなく「Plugin API」なのか？
Composerで自動化を行う際、多くの方が最初に思い浮かべるのが `composer.json` の `scripts` セクションです。例えば、`post-install-cmd` などにシェルスクリプトを登録する方法ですね。
もちろん、それも一つの手です。しかし、`scripts` には以下のような弱点があります。
- OS依存の問題（WindowsのPowerShellと、macOS/LinuxのBashでコマンドが異なる）
- 複雑な条件分岐（「すでに `.env` が存在する場合は上書きしない」など）を書くのがシェルスクリプトだと面倒
- 再利用性が低い（他のプロジェクトに持ち回りにくい）
ここで登場するのが、今回解説するComposer Plugin APIです。
Composerの内部構造（EventDispatcherやPluginManager）に直接PHPのコードでフックするため、クロスプラットフォーム（OSを問わず動く）であり、厳密なエラーハンドリングやComposer内部のAPIをフル活用した高度な自動化が可能になります。
—
2. 実装の全体像とアーキテクチャ
今回作成するプラグインの動作フローは非常にシンプルです。
1. ユーザーが `composer install` または `composer update` を実行する。
2. Composerが内部でイベント（`POST_INSTALL_CMD` や `POST_UPDATE_CMD`）をディスパッチする。
3. 私たちが作成した独自Pluginがそのイベントをキャッチする。
4. プラグイン内のPHPコードが走る：
- プロジェクトのルートディレクトリに `.env` が存在するか確認する。
- 存在しなければ、`.env.example` をコピーして `.env` を自動生成する。
- 成功メッセージをコンソールに美しく出力する。
それでは、実際に手を動かしてこの仕組みを作っていきましょう！
—
3. 独自Composerプラグインのハンズオン実装
今回は、「`my-company/env-auto-generator-plugin`」という名前のローカルプラグイン（または独立したパッケージ）を作成する手順で解説します。
ステップ1: プラグイン用ディレクトリの作成と `composer.json` の定義
まずは、プラグインとなるPHPパッケージの設計図を作ります。適当なディレクトリ（例: `env-generator-plugin`）を切って、その中に `composer.json` を配置してください。
{
“name”: “my-company/env-auto-generator-plugin”,
“description”: “Composer install直後に.env.exampleから.envを自動生成する実用プラグイン”,
“type”: “composer-plugin”,
“license”: “MIT”,
“require”: {
“php”: “>=8.1”,
“composer-plugin-api”: “^2.0”
},
“autoload”: {
“psr-4”: {
“MyCompany\\Composer\\EnvGenerator\\”: “src/”
}
},
“extra”: {
“class”: “MyCompany\\Composer\\EnvGenerator\\EnvGeneratorPlugin”
}
}
ここがポイント！重要な設定の解説：
- `”type”: “composer-plugin”`: これがComposerに対して「これは単なるライブラリではなく、Composerの挙動を拡張するプラグインだ」と伝える魔術の呪文です。
- `”composer-plugin-api”: “^2.0″`: 現在主流であるComposer Plugin API v2を指定しています。v1に比べてメモリ効率や安全性が劇的に向上しています。
- `”extra”: {“class”: “…”}`: Composerがプラグインをロードした際に、最初にどのPHPクラスをインスタンス化すればよいかのエントリーポイントを指定しています。
—
ステップ2: PluginInterfaceを実装するメインクラスの作成
次に、先ほど指定したエントリーポイントとなるクラス `src/EnvGeneratorPlugin.php` を作成します。
Composerのプラグインは、`Composer\Plugin\PluginInterface` と、イベントを購読するための `Symfony\Component\EventDispatcher\EventSubscriberInterface` の2つを実装するのが基本形です。
/
class EnvGeneratorPlugin implements PluginInterface, EventSubscriberInterface
{
protected Composer $composer;
protected IOInterface $io;
/
- プラグインが有効化された時にComposerから呼び出される初期化メソッド。
/
public function activate(Composer $composer, IOInterface $io): void
{
$this->composer = $composer;
$this->io = $io;
}
public function deactivate(Composer $composer, IOInterface $io): void
{
// プラグイン無効化時のクリーンアップ処理（今回は特に何もしません）
}
public function uninstall(Composer $composer, IOInterface $io): void
{
// プラグインアンインストール時の処理（今回は特に何もしません）
}
/
- このプラグインが購読（リスン）するComposerイベントを定義する。
- ここで指定したイベントが発生すると、紐づいたメソッドが自動実行されます。
/
public static function getSubscribedEvents(): array
{
return [
// パッケージのインストールが完了した直後のイベントをフック
ScriptEvents::POST_INSTALL_CMD => ‘onPostInstallOrUpdate’,
// パッケージのアップデートが完了した直後のイベントも同様にフック
ScriptEvents::POST_UPDATE_CMD => ‘onPostInstallOrUpdate’,
];
}
/
- install/update完了直後に走る実際の処理ロジック。
/
public function onPostInstallOrUpdate(Event $event): void
{
// Composerの実行コンテキストから、プロジェクトのルートディレクトリを取得
// getVendorDir() の一つ上の階層が、通常のプロジェクトルートになります
$vendorDir = $this->composer->getConfig()->get(‘vendor-dir’);
$projectRoot = dirname($vendorDir);
$envFile = $projectRoot . ‘/.env’;
$envExampleFile = $projectRoot . ‘/.env.example’;
// 1. .env.example が存在しない場合は何もしない（安全装置）
if (!file_exists($envExampleFile)) {
return;
}
// 2. すでに .env が存在する場合は、ユーザーの設定を上書きしないようにスキップする
if (file_exists($envFile)) {
$this->io->write(“
$this->io->write(“
return;
}
// 3. .env.example を .env にコピーする
if (copy($envExampleFile, $envFile)) {
// IOInterface を使うことで、Composerの綺麗なフォーマットでコンソールにメッセージを出力できる
$this->io->write(“
} else {
$this->io->writeError(“
}
}
}
プロのアーキテクトからのワンポイントアドバイス：
`echo` や `print` を使わず、`IOInterface->write()` を使っている点に注目してください。これにより、Composerが持つ `–quiet`（静音モード）や `–verbose`（詳細出力モード）といったオプションと美しく協調動作し、CI/CD環境でのログの汚染を防ぐことができます。
—
4. 動作確認：いよいよ「HelloWorld」を体験する
私たちが作ったプラグインを、実際のプロジェクトで動かしてみましょう。
今回は動作テストのために、適当なテスト用アプリケーションディレクトリ（例: `my-test-app`）を別に用意します。
ステップ1: テストアプリ側からプラグインを読み込ませる
テストアプリ側の `composer.json` に、先ほど作成したローカルプラグインへのパスを指定します（開発中は `path` リポジトリを使うと非常に便利です）。
{
“name”: “my-org/my-test-app”,
“type”: “project”,
“require”: {
“my-company/env-auto-generator-plugin”: “”
},
“repositories”: [
{
“type”: “path”,
“url”: “./path/to/env-generator-plugin” // プラグインを置いた実際のパスを指定
}
],
“minimum-stability”: “dev”
}
ステップ2: あえて `.env` を削除した状態で `composer install` を実行！
テストアプリのルートディレクトリに、あらかじめ `.env.example` だけを置いておきます（中身は `APP_ENV=local` など適当でOKです）。この状態で、`.env` は存在しないことを確認してください。
さあ、心拍数を少し上げて、以下のコマンドを実行してみましょう！
composer install
実行ログのイメージ：
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
- Installing my-company/env-auto-generator-plugin (dev-main)
Writing lock file
Generating autoload files
> MyCompany\Composer\EnvGenerator\EnvGeneratorPlugin::onPostInstallOrUpdate
[EnvGeneratorPlugin] 成功: .env.example から .env ファイルを自動生成しました！
1 package suggestions were available.
Use an internal ‘suggests’ command to see `composer update` の直後、または `composer install` が走った瞬間に、自作プラグインがイベントをキャッチし、魔法のように `.env` ファイルを生成してくれたのがお分かりいただけますでしょうか？
もう一度 `composer install` を叩いてみてください。今度は次のようなメッセージが出ます。
[EnvGeneratorPlugin] .env ファイルはすでに存在するため、生成をスキップしました。
（新規に項目を追加した場合は手動で .env.example を確認してください）
既存の環境設定が誤って上書きされるのを完璧にガードできています。これぞ、現場で求められる堅牢な自動化設計です。
—
5. まとめと、実務でさらに活かすためのネクストステップ
今回は、Composerの「Plugin API」を用いて、パッケージインストール直後に `.env` を自動生成するプラグインの実装方法を解説しました。
- PluginInterface と EventSubscriberInterface を組み合わせることで、Composerのライフサイクルに独自の処理を安全に組み込めること。
- シェルスクリプトに頼らず、PHPでロジックを書くことでOS依存を無くし、保守性を劇的に高められること。
- `IOInterface` を活用して、Composerの出力スタイルに馴染むスマートなメッセージングができること。
これをマスターすれば、毎日のコーディング前の儀式や、チームメンバーの「あ、初期設定忘れて動かないんだけど！」という無駄なトラブルシューティングの時間をゼロにすることができます。
さらに実務へと応用するならば、
- `.env` 生成と同時に、アプリケーション暗号化キー（Laravelの `key:generate` のような処理）を自動で書き込む
- 開発環境に必要なダミーのパーミッション設定（ログディレクトリの作成など）を一緒に行う
といった拡張も容易に可能です。
ぜひ、あなたのチームのプロジェクトにもこの仕組みを取り入れて、開発ストレスのない快適な環境を手に入れてください。それでは、また次回のアーキテクチャ解説でお会いしましょう！