PhpStorm External Tools 極限活用論：IDEとコンテナを直結させる「右クリック統合せよ」
開発効率のボトルネックは、人間がコンテキストをスイッチする瞬間に発生する。
ターミナルを開き、DockerコンテナのIDを確認し、`docker exec` を叩いてComposerスクリプトを実行する。あるいは、レガシーなコード整形ツールのためにわざわざ別コマンドを打つ。
――無駄だ。極限までチューニングされた開発環境において、指先がIDEから離れる時間はすべて「悪」である。
本稿では、PhpStormの機能拡張の隠し札である 「External Tools（外部ツール）」 を用い、単なるコマンドのショートカット登録を超えた、Docker環境・CI/CDパイプライン・独自CLIをIDEの右クリックメニューおよびグローバルショートカットへ完全に融合させる設計手法を解説する。
マニュアルをなぞるだけの解説はしない。IDEのプロセスモデル、標準入出力のストリーム処理、そしてコンテナ境界をいかにシームレスに超越するかという、アーキテクト視点での極限の自動化手法を叩き込む。
—
1. 内部アーキテクチャの理解：External Toolsは何を動かしているのか？
多くのエンジニアは、External Toolsを「シェルスクリプトをボタンで実行する簡易マクロ」程度に捉えている。しかし、その内部挙動を理解すれば、これがIDEとOSプロセス、さらにはDockerデーモンを繋ぐ強力なパイプラインであることがわかる。
プロセス起動とマクロ変数の解決メカニズム
External Toolsを実行した瞬間、PhpStormのJVMはバックグラウンドでOSのプロセスを生成する。この際、IDEが保持している現在のコンテキスト（開いているファイルの絶対パス、プロジェクトのルートディレクトリ、選択中の行番号など）を、マクロ変数（例: `$FileRelativePath$` や `$ProjectFileDir$`）を通じて引数として動的に注入する。
[PhpStorm (JVM)]
│
├─ コンテキスト解析 (File, Path, Selection)
├─ マクロ変数の展開 ($FilePath$ -> /app/src/Controller/Foo.php)
│
▼
[OSプロセス / Docker CLI] ──> 標準入出力・エラーをIDEの「Run」タブへリアルタイムストリーミング
この仕組みをハックすることで、「今、自分がエディタで開いているまさにそのクラスやファイル」を対象にした独自の静的解析、コード生成、デプロイメントパイプラインを、右クリック一撃で発動させることが可能になる。
—
2. 実践：Dockerコンテナ環境を前提とした「Composer & 静的解析」の完全統合
昨今のモダンなPHP開発において、PHP本体やComposerがローカルホストのグローバル環境にインストールされていることは稀である。大半はDocker（Sail、Lando、あるいは独自のCompose構成）上で稼働しているはずだ。
「ローカルのPhpStormから、Dockerコンテナ内のCLIを叩く」という要件を、External Toolsを用いて極限までエレガントに実現する設定を構築する。
設定手順の全体像
PhpStormの `Settings (Preferences)` > `Tools` > `External Tools` から新規作成を行う。
以下の設定は、プロジェクト内のDocker Compose環境（`docker compose`）に対し、現在エディタでフォーカスしているファイルを引数として渡すPHPStan（静的解析）の統合例である。
1. 外部ツール設定値 (PHPStan on Docker)
- Name: `[Docker] Run PHPStan on Current File`
- Description: 現在開いているファイルを対象にDocker上のPHPStanを実行する
- Program: `/usr/local/bin/docker` （またはOS上のdockerバイナリパス）
- Arguments:
compose exec -T php vendor/bin/phpstan analyse $FileRelativePath$ –level=max –no-progress
- 引数の解説: `-T` オプションによりTTYを無効化し、CI環境やIDEのコンソールでもクリーンなストリーム出力を維持する。`$FileRelativePath$` を使うことで、プロジェクトルートからの相対パスが動的に渡される。
- Working directory:
$ProjectFileDir$
- 解説: プロジェクトのルートディレクトリをワーキングディレクトリとして指定する。
—
3. 現場で震えるほど役立つ：高度なカスタムスクリプト連携
単発のコマンド実行だけでは物足りない。複数のCLIコマンドをチェインさせ、さらに実行結果をPhpStormのエディタにフィードバックする実践的なスクリプトを統合する。
ここでは、「Composerのカスタムスクリプト実行 ＋ 独自コードフォーマット規約の強制 ＋ 失敗時の通知」をワンアクションで行う実戦的アプローチを示す。
ホスト側ラッパースクリプトの作成 (`bin/ide-cs-fixer.sh`)
プロジェクトのルートに、IDEからキックされる専用のシェルスクリプトを配置する。これにより、複雑なDockerコマンドや環境変数のインジェクションをスクリプト側にカプセル化できる。
!/usr/bin/env bash
==============================================================================
Script Name: ide-cs-fixer.sh
Description: PhpStormからキックされ、Docker上のPHP-CS-FixerとLinterを連続実行する
==============================================================================
set -euo pipefail
1. 引数として渡されたファイルのパスを受け取る
TARGET_FILE=”${1:-}”
if [ -z “$TARGET_FILE” ]; then
echo “Error: Target file is not specified.” >&2
exit 1
fi
echo “==> [1/2] Running PHP-CS-Fixer for: ${TARGET_FILE}”
Dockerコンテナ内のPHP-CS-Fixerを対象ファイルのみに実行
docker compose exec -T php vendor/bin/php-cs-fixer fix “${TARGET_FILE}” –verbose
echo “==> [2/2] Running Static Analysis on: ${TARGET_FILE}”
続けて構文・型チェックを実行
docker compose exec -T php vendor/bin/phpstan analyse “${TARGET_FILE}”
echo “==> All checks passed successfully for ${TARGET_FILE}!”
PhpStorm External Toolsへの登録設定
上記のスクリプトをPhpStormから呼び出すための設定をJSON（設定のエクスポート形式）の概念で示す。