伝説のテックリードが伝授する：PhpStorm ✕ Xdebug 3で実現する「秒速ステップデバッグ」の極意
テックリードの私から言わせてもらえば、いまだに `var_dump()` や `dd()`、果てはログファイルへの出力でバグを追っているエンジニアを見るたびに、心の中で盛大に頭を抱えたくなります。それらの手法は、暗闇の中で手探りでモンスターを探すようなものです。
モダンなWeb開発において、IDEのデバッガーを使いこなせないのは、F1マシンのコックピットでマニュアル車のシフト操作をしているようなもの。数分、いや数秒で解決できるバグに何時間も溶かすのは、チーム全体にとって最大の機会損失です。
今回は、PhpStormとXdebug 3を組み合わせ、ブラウザからのリクエストを完璧に捕捉してステップ実行するための「本番環境レベル」の完全設定ガイドを伝授します。マニュアルのコピペではない、内部の通信構造や実務で確実にハマる罠を踏まえた「生きた知見」をすべてここに置いていきます。
—
1. Xdebug 3 内部構造の理解：なぜ「3」への移行が絶対条件なのか
まず前提として、Xdebug 2系と3系では、内部のアーキテクチャと設定思想がガラリと変わっています。2系で散見された「設定の複雑さ」や「パフォーマンスの劣化」は3系で完全にリファクタリングされました。
Xdebug 3がIDEと通信する仕組み
1. トリガーの発動: ブラウザからリクエストが飛ぶ際、Cookie（`XDEBUG_SESSION=PHPSTORM`）やクエリパラメータ、あるいは環境変数によって「デバッグモード」が有効化されます。
2. DBGpプロトコル: PHPの実行エンジン（Zend Engine）とPhpStormの間で、DBGpという専用のデバッグプロトコルを用いたTCPソケット通信（デフォルトポート: `9003`）が確立されます。
3. プロセスの完全掌握: PhpStorm側で「リスナー」が起動していれば、PHPの実行は最初の行（またはブレークポイント）で一時停止し、メモリ上の全変数、コールスタック、グローバル領域のデータがIDEに吸い上げられます。
—
2. 実務で確実に動く `php.ini` のベストプラクティス構成例
「設定したのにブレークポイントで止まらない」というトラブルの9割は、`php.ini` の記述ミス、あるいはXdebug 3特有の新ディレクティブへの理解不足に起因します。
以下に、ローカル開発環境（Docker / Homestead / 仮想環境含む）で最も堅牢に動作する設定を示します。
[xdebug]
; Xdebug 3における必須のモード指定。ステップデバッグを行うには “debug” を必ず含める
xdebug.mode = debug
; リクエストと同時に自動でデバッグを開始する（ブラウザ拡張機能やCookieなしでも強制停止させたい場合に有効）
xdebug.start_with_request = yes
; IDE（PhpStorm）が稼働しているホストのIP/ポート設定
; Xdebug 3ではデフォルトポートが 9000 から 9003 に変更されている点に注意
xdebug.client_port = 9003
; Docker環境の場合はホストマシンを指すIP（Linuxなら 172.17.0.1 や host.docker.internal）を指定
; 宿主マシンのIPアドレスを動的に解決させたい場合は “trigger” や “localhost” を適切に調整
xdebug.client_host = “127.0.0.1”
; ログ出力設定：接続エラーが発生した際の原因究明に不可欠。必ずパスを通しておくこと
xdebug.log = “/var/log/xdebug/xdebug.log”
xdebug.log_level = 7
> architect’s note: `xdebug.client_host` について、Dockerコンテナからホスト側のPhpStormへ接続する場合、Linux環境では `host.docker.internal` が名前解決できないケースがあります。その場合は Docker のネットワーク設定でブリッジIPを明示するか、コンテナ起動時に `–add-host=host.docker.internal:host-gateway` を付与してください。
—
3. PhpStorm側の「神設定」とリスナーの極意
PHP側の準備ができたら、次はPhpStorm側の迎撃態勢を整えます。ここを間違えると、永遠に「黄色の虫アイコン」が点灯しません。
A. ゼロコンフィグ・リスニングの有効化
PhpStormの右上にある「電話の受話器アイコン（Start Listening for PHP Debug Connections）」を緑色にします。
- これにより、PhpStormはポート `9003` で常時待機状態となり、外部から飛んできたデバッグセッションを自動キャッチします。
B. パス・マッピング（Path Mapping）の絶対的な正解
ローカル環境がDockerや仮想マシン上にあり、ソースコードがホストマシンと同期されている場合、絶対パスの差異によりPhpStormがブレークポイントを認識できません。
1. `Settings (Preferences) > PHP > Servers` を開く。
2. サーバ名（例: `local-docker-server`）、ホスト名（例: `localhost`）、ポート（例: `80`）を適切に入力。
3. 「Use path mappings」にチェックを入れる。
4. プロジェクトのルートディレクトリに対し、コンテナ内の絶対パス（例: `/var/www/html`）を正確にマッピングする。
—
4. トラブルシューティング：なぜブレークポイントで止まらないのか？
現場で遭遇しがちな「絶望の3大原因」と、その秒速解決法を共有します。
事例1: ブラウザからリクエストを送ってもPhpStormが反応しない
- 原因: Xdebug 3のポートが `9003` ではなく、古い `9000` のままになっている（PHP-FPMがポートを競合している可能性）。
- 解決: `phpinfo();` を出力し、`xdebug.client_port` が `9003` になっているか、また `xdebug.log` に `Connection refused` などのエラーが出ていないか確認する。
事例2: ブレークポイントに斜めの「×（バツ印）」がつき、機能しない
- 原因: 前述の「パス・マッピング」が間違っている、またはPhpStormが該当ファイルのソースコードを認識できていない。
- 解決: デバッグセッションが開始された際、PhpStorm下部に表示される「Incoming File Path」の通知を確認し、マッピングを正しく修正する。
事例3: 非同期通信（AJAX / APIリクエスト）やCLIでデバッグしたい
- 解決: Chrome / Firefox の公式拡張子 「Xdebug helper」 をインストールし、ブラウザ側でセッションを「Debug」モードに明示的に切り替える。CLIの場合は環境変数を噛ませて実行します：
XDEBUG_TRIGGER=1 php artisan migrate
—
5. 開発スピードを爆発的に高める！PhpStorm デバッグ時の隠しショートカット
ここからが本題です。ステップ実行中にマウスをカチカチ動かしているようでは、一流のエンジニアとは言えません。キーボードだけで全てを完結させます。
| ショートカット (Win/Linux) | ショートカット (Mac) | 動作・役割 | テック流の活用術 |
| :— | :— | :— | :— |
| `F9` | `⌥⌘R` | Resume Program | 次のブレークポイントまで一気に処理を進める。 |
| `F8` | `F8` | Step Over | 関数に入らず、現在の行の処理を完了して次の行へ進む。 |
| `F7` | `F7` | Step Into | 実行中の行にあるメソッドや関数の内部へ潜り込む。 |
| `Shift + F8` | `⇧F8` | Step Out | 現在のメソッドの残りの処理を即座に実行し、呼び出し元へ戻る。 |
| `Alt + F9` | `⌥F9` | Run to Cursor | カーソルがある行まで一気にコードを実行する（無駄なF8連打からの解放）。 |
| `Alt + F8` | `⌥F8` | Evaluate Expression | 任意の式やメソッドをその場で評価・実行し、戻り値を確認する。 |
> 神の技 `Evaluate Expression (⌥F8)`:
> デバッグ停止中にこのショートカットを叩くと、現在のスコープの変数を自由にいじったり、`$this->repository->findBy(1)` のような複雑なクエリをその場で実行して結果を確認できます。コードを書き直してリロードする手間が完全に消滅します。
—
6. チーム開発を加速させる：設定の共有化ルール
個人のマシーン環境に依存したデバッグ設定は、チーム開発の不協和音を生みます。プロジェクト全体でデバッグ環境を統一するため、以下の構成管理を徹底してください。
`.idea/` ディレクトリの適切なバージョン管理
PhpStormの設定ファイル群（`.idea/`）のうち、デバッグサーバーやPHPの解釈パス定義が含まれる `.idea/php.xml` や `.idea/servers.xml` は、チーム間で共有すべきです。
ただし、個人のローカルパスに依存する設定（例: ユーザ固有のPHP実行バイナリパスなど）は混入しやすいため、`.gitignore` で適切にフィルタリングしつつ、共通のDocker環境を前提とした `php.xml` はGit管理下に置くのがベストプラクティスです。
`php.xml` (ベストプラクティス構成断片)
—
結びにかえて
XdebugとPhpStormのステップ実行をマスターした瞬間から、あなたの「バグ調査」という苦行は、コードの内部構造を透視する「知的エンターテインメント」へと変貌します。
「なぜこの変数が null になるのか？」
「どのタイミングで意図しないオーバーライドが発生したのか？」
それを推測ではなく、「事実（ファクト）」として目の前の画面でミリ秒単位で捉えられること。これこそが、卓越したエンジニアが圧倒的なスピードで高品質なシステムを組み上げられる理由です。
さあ、今すぐ `php.ini` を書き換え、PhpStormの受話器を緑色に光らせてください。あなたの開発ライフスタイルが劇的に変わることを、私が保証します。