【実務・中級編】PhpStormの「Run Configuration」テンプレートをチーム共有して実行コマンドの差異を撲滅する – 総合開発環境（IDE）生産性向上バイブル

はじめに：なぜあなたのチームは「動かない環境」に時間を溶かすのか

「手元の環境では動くのに、staging環境やCIで落ちる」
「新規メンバーのオンボーディングに3日もかかり、最初のタスクに着手する前に疲弊している」
「誰が書いたかわからないシェルスクリプトや、各自のIDEにバラバラに手打ちされた複雑なデバッグ引数が野放しになっている」

開発現場でテックリードを務めるあなたなら、この悪夢のような状況に幾度となく直面してきたはずだ。特にPHP（SymfonyやLaravelなど）を用いたモダンなWeb開発において、アプリケーションの実行コンテキストは複雑化の一途をたどっている。Dockerコンテナ内の特定のPHPバージョン、Xdebug用の環境変数、メモリ制限（`memory_limit=-1`）、非同期キューのワーカー起動、PHPUnitの特定フィルタ設定——これらを開発者個人の記憶や、乱雑に散らかったMarkdownのドキュメントに頼って管理している時点で、チームの生産性は確実に蝕まれている。

世界最高峰のPHP統合開発環境である PhpStorm には、このカオスを根絶し、チーム全体の実行コマンドを完全同期させるための強力な機構が備わっている。それが 「Run Configuration（実行構成）」の`.run`フォルダーによるGit管理 だ。

本記事では、単なるマニュアルの焼き直しではない。PhpStormの内部アーキテクトとしての視点から、実行構成のプリセット化による環境差異の完全撲滅手法、開発スピードを極限まで引き上げる隠しコマンド、そして実務で即座にコピー＆ペーストして使えるプロダクションクオリティの設定ファイルの実装パターンを魂を込めて伝授する。

—

1. チーム開発の生産性を底上げする「神プラグイン」選

PhpStormはそのままでも強力だが、チーム全体の「開発体験（Developer Experience）」を統一し、ヒューマンエラーを物理的に排除するためには、以下のプラグインが不可欠だ。

EnvFile
導入すべき理由: `.env`ファイルをRun Configurationに直接アタッチし、実行時に環境変数を安全かつ動的にロードするための決定版プラグイン。開発者ごとに異なるクレデンシャルやデバッグフラグの混入を防ぐ。
Key Promoter X
導入すべき理由: マウス操作を検知し、対応するキーボードショートカットをポップアップで執拗に教え込んでくれる教育的プラグイン。チーム全体のタイピング比率を高め、エディタ操作の速度を底上げする。
Ameba / PHP Inspections (EA Extended)
導入すべき理由: 標準のインスペクションを補完し、チームで合意したコーディング規約やアンチパターンを静的に検知。コードレビューのcognitive load（認負荷）を劇的に下げる。

—

2. 開発スピードを劇的に高める隠れたキーボードショートカット

マウスに手を伸ばした瞬間、あなたの脳内フローは分断される。以下のショートカットを指に叩き込み、思考の速度とコードの生成速度を同期させよ。

—

3. 核心：`.run` フォルダーによるRun ConfigurationのGit共有アーキテクチャ

従来、PhpStormの実行構成（どのスクリプトを、どの引数と環境変数で実行するか）は、プロジェクトルートの `.idea/` ディレクトリ配下に保存されていた。`.idea/` は個人ごとのワークスペース設定（ウィンドウの位置やローカル履歴など）が多く含まれるため、`.gitignore` に指定するのが定石だった。

しかし、PhpStorm 2020.1以降、実行構成やデバッグ設定を プロジェクトルート直下の `.run/` フォルダー（または `.jetbrains/runConfigurations/`）に分離してJSON/XML形式で保存し、Git管理できる仕組み が標準サポートされている。

なぜこれがゲームチェンジャーなのか？

1. 環境のコード化（Configuration as Code）: 実行コマンドがソースコードと共にバージョン管理されるため、アプリケーションの仕様変更に合わせて実行構成も進化させられる。
2. 新規参画者のオンボーディングコストの消滅: リポジトリをクローンした瞬間、チーム標準のテスト実行、Docker連携コマンド、マイクロサービスの起動プリセットが右上のドロップダウンに何の手間もなく現れる。
3. 「俺の環境では動く」の永久追放: 引数のタイポや、環境変数の設定漏れによるバグが物理的に発生しなくなる。

—

4. 実戦で即座に使える！ `.run` 設定ファイルのベストプラクティス

ここでは、モダンなDockerベースのPHP/Symfony/Laravel開発環境を想定し、実務でそのまま使える2つの重要なRun Configuration設定ファイルを提示する。これらをプロジェクトの `.run/` ディレクトリに配置せよ。

パターンA: Docker Compose経由でのPHPUnit実行設定

開発者のローカルマシンにPHPがインストールされていなくても、Dockerコンテナ内で正確なバージョンのPHPUnitを同一のコマンド体系で実行するための設定ファイル。

ファイル名: `.run/Docker PHPUnit.run.xml`

パターンB: 複合実行（Compound）による一括起動設定

バックエンドのAPIサーバー、非同期キューワーカー、そしてフロントエンドのVite開発サーバーを、開発者が1クリック（または1ショートカット）で一斉に立ち上げるための設定。

ファイル名: `.run/Start All Services.run.json`

{
“version”: “4”,
“configurations”: [
{
“type”: “CompoundRunConfigurationType”,
“name”: “Start All Services”,
“todo”: “フロント・バックエンド・ワーカーを同時に起動し、開発環境を1アクションで構築する”,
“parallel”: true,
“runConfigurations”: [
{
“type”: “PhpWebAppRunConfigurationType”,
“name”: “Docker Web Server”
},
{
“type”: “PhpRemoteDebugConfigurationType”,
“name”: “Listen for Xdebug”
},
{
“type”: “PHPUnitRunConfigurationType”,
“name”: “Docker PHPUnit”
}
]
}
]
}

※JSONフォーマットの補足: `parallel: true` を指定することで、複数のタスクをブロックせずに並行起動させることができる。これにより、デバッグリスナーを待機させながらWebサーバーを立ち上げるといった複雑なマルチプロセス開発環境が瞬時に手に入る。

—

5. チーム導入を成功させるためのガバナンスと運用ルール

ただファイルを置くだけでは、現場のエンジニアが古いカスタム構成を使い続けたり、勝手に書き換えて混乱するリスクがある。テックリードとして以下のガバナンスを効かせよ。

1. `.run/` 配下のイミュータブル（不変）化

チーム共通の標準コマンド（テスト、Linter、ビルダー）はすべて `.run/` に含めてGit管理し、個人のローカル専用構成は極力作らせない文化を作る。

2. CIパイプラインとの同期

GitHub ActionsやGitLab CIで実行しているコマンド群を、そのままPhpStormのRun Configurationに落とし込む。CIで落ちるテストは、開発者の手元でも1発のショートカット（`Ctrl + Shift + R`）で完全に再現できなければならない。

3. オンボーディングドキュメントの簡素化

「リポジトリをクローンする ➔ PhpStormでプロジェクトを開く ➔ 右上のプルダウンから『Start All Services』を選んで実行ボタンを押す」
新規メンバーへの説明はこの3ステップだけで完了する状態を目指せ。

—

おわりに：環境の差異に悩む時間を、コードを書く時間へ

開発環境の差異や、コマンドの打ち間違い、不統一なデバッグ設定。これらはエンジニアの創造的なエネルギーを静かに、しかし確実に削ぎ落としている。

PhpStormの `.run` フォルダーによる実行構成の共有化は、単なる便利機能ではない。それは 「チーム全体の開発コンテキストをコードとして同期し、インフラストラクチャの迷子をゼロにする」 という、極めて高度なエンジニアリングプラクティスだ。

今日からあなたのプロジェクトのルートに `.run/` を作り、チーム全員の実行コマンドを統一せよ。浮いた膨大な時間とcognitive loadの軽減分は、より本質的なアーキテクチャの設計や、美しいコードの執筆へと全振りするのだ。プロフェッショナルとしての真価を、その手元のIDEから示してほしい。