開発環境の差異を「物理的に」撲滅せよ：PhpStorm `.run` テンプレートのGit管理とDocker完全統合アーキテクチャ
こんにちは、DevOpsリードアーキテクトの私だ。
開発現場において、「私のローカル環境では動くのに、ステージングや別のメンバーの環境では落ちる」という現象ほど、エンジニアの認知リソースを無駄に消費するものはない。特にPHP / Webフロントエンドの混成プロジェクトにおいて、PhpStormの実行設定（Run Configuration）の差異は、隠れたバグの温床であり、新規参画者のオンボーディングを遅延させる最大の障壁だ。
「composerのスクリプト名を忘れた」「Xdebugのポート番号が競合した」「テスト実行時の環境変数が抜けていた」——こうしたヒューマンエラーに依存したオペレーションを、現代のプロフェッショナルチームが許容する余地はない。
今回は、PhpStormの `.run` ディレクトリを活用し、実行コマンドの差異を完全に撲滅する。さらに、Docker環境との完全自動同期、CI/CDパイプラインとの親和性を極限まで高めた、エリートチームのための構成管理術を授けよう。
—
1. 内部アーキテクチャ：PhpStormが実行設定を処理するメカニズム
なぜ、GUIでポチポチと設定するだけのRun Configurationを語る必要があるのか？ それは、PhpStormがプロジェクトルートの `.run/`（または `.idea/runConfigurations/`）配下にあるXMLファイルを完全なコードとして解釈・ロードしているからだ。
[Your-Project-Root]/
┣ .run/ <-- ここをGit管理する
┃ ┣ PHPUnit_Docker.xml <-- コンテナ内テスト実行定義
┃ ┣ Pest_Feature_Test.xml <-- ターゲットを絞ったPest実行定義
┃ ┗ ECS_CS_Fixer_PreCommit.xml <-- 静的解析・フォーマット定義
┣ src/
┗ composer.json
IDEの内部では、これらXMLファイルは `RunnerAndConfigurationSettings` インスタンスとしてメモリ上にマッピングされる。GUIで行う設定変更は、実質的にこのXMLの差分生成に他ならない。つまり、このXML自体をチーム標準としてGit管理下に置けば、全エンジニアのIDE環境が完全に同期されることになる。
—
2. 実装：Dockerコンテナを直叩きする堅牢な `.run` XMLの構築
多くの開発者が陥る罠は、ホストマシンのPHPバイナリを直接叩くRun Configurationを作ってしまうことだ。これではホストのPHPバージョン依存が発生し、Dockerでコンテナ化している意味が薄れる。
ここでは、「Docker Composeのサービスに対して、環境変数をインジェクションしつつアタッチする」実戦的なXMLテンプレートを提示する。
以下のファイルを `.run/PHPUnit_Docker.xml` としてプロジェクトに配置せよ。
この設定がもたらす圧倒的なメリット
1. 環境の完全なカプセル化: ホスト側にPHPやComposerがインストールされていなくても、Dockerさえ動いていれば一発でテストが走る。
2. Xdebugの即時有効化: `XDEBUG_MODE=debug` がハードコーディングされているため、ブレークポイントを置くだけでコンテナ内のコードデバッグが即座に開始できる。
3. 実行前タスクの自動化: `method` タグにより、テスト実行の直前に自動で `composer dump-autoload` が走るため、クラスのオートロード漏れによるテスト失敗を物理的に防止する。
—
3. 応用：CI/CDパイプラインとRun Configurationの融合
最高のエコシステムとは、ローカルIDEとCI/CD（GitHub Actions / GitLab CI等）で全く同じ実行コマンド・文脈が維持されている状態だ。
PhpStormの `.run` 構成は、JetBrains公式のCLIツールである Qodana や、コマンドラインランナー（`phpstorm.sh` / `phpstorm64.exe` のヘッドレスモード）から呼び出すことができる。
例えば、GitHub Actionsのワークフロー内で、IDEが持っている設定をそのままヘッドレス実行させたい場合、以下のようなステップを組むことが可能だ。
.github/workflows/ide-config-test.yml の抜粋
name: IDE Run Configuration Validation
on: [pull_request]
jobs:
validate-run-configs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Validate .run XML Schemas
run: |
# .run配下のXMLが構文エラーを起こしていないかチェック
for file in .run/.xml; do
python3 -c “import xml.etree.ElementTree as ET; ET.parse(‘$file’)” || exit 1
:done
echo “All Run Configurations are syntactically valid.”
さらに、開発者がローカルで実行するタスクと、CIで流すテストコマンドが「完全に同一のXML定義」に紐づいているため、「ローカルではパスするのにCIで落ちる」というカオスなデバッグ地獄から永遠に解放される。
—
4. エキスパートハック：マクロとプレースホルダーによる動的パラメータ制御
複雑なマイクロサービスやマルチテナントのPHPアプリケーションでは、実行ごとに引数やターゲットを変えたいケースがある。PhpStormのプレースホルダーを活用すれば、柔軟性と標準化を両立できる。
以下の設定は、選択したファイルやカーソル行のテストを、Docker上のPestでピンポイント実行するテンプレート（`.run/Pest_Single_Test.xml`）だ。
これをGit管理しておけば、チームメンバー全員が `Ctrl + Shift + R`（Macは `Control + Shift + R`）のショートカット一発で、今見ているテストメソッドを瞬時にDockerコンテナ上で実行できる。コンテキストスイッチのコストはゼロになる。
—
5. 導入時の運用ガイドライン：チームへの強制と合意形成
技術的に `.run` を共有しても、メンバーが勝手に設定をローカルでいじり倒してプッシュしなくなっては意味がない。以下のガバナンスをチームに敷くこと。
1. `.run/` 配下の強制バージョン管理
- `.gitignore` から `.run/` を除外し、必ずリポジトリに含める。
- 個人の趣味嗜好が入る一時的な実行設定は、ユーザー固有のストレージ領域（ `.idea/workspace.xml` 等、Git除外対象）に留め、チーム共有すべきものは必ず `.run/` に昇格させる。
2. 新規参画者のオンボーディングの自動化
- リポジトリをクローンし、PhpStormでプロジェクトを開いた瞬間、右上の実行ドロップダウンに「PHPUnit (Docker Container)」「Pest (Current Context)」といった標準メニューが並んでいる状態を作る。
- 「環境構築の手順書」という名のドキュメントは今日から廃止せよ。「IDEを開けば、すでに準備は完了している」状態こそが、真のDevOpsである。
—
結び：開発環境の「不確実性」をエンジニアリングで殺せ
開発効率の低下の多くは、ツール自体の性能不足ではなく、「環境のバラつき」という極めてアナログな要因に起因する。
PhpStormの `.run` テンプレートのGit管理は、単なる便利機能ではない。それは、チーム全体の実行コンテキストをコード化し、開発プロセスの再現性を担保するための強力なガバナンスツールである。
今すぐプロジェクトに `.run` ディレクトリを作り、チームの標準実行環境をコードとしてコミットせよ。あなたのチームの開発スピードは、その瞬間から一段上のステージへとシフトする。