【実務・中級編】Xdebug 3 vs Xdebug 2：何が変わった？バージョン移行時に知るべき変更点まとめ – デバッグ・コード品質・テストツール生産性向上バイブル

Xdebug 3完全移行バイブル：旧設定を捨て、開発スピードを極限まで引き上げるアーキテクチャの真実

テックリードの皆さん、日々のPHPアプリケーション開発において「デバッグの遅延」や「謎の挙動に数時間を溶かす不毛な時間」にフラストレーションを感じていないだろうか。

世の中には「とりあえず `var_dump()` を仕込んでリロードする」という前近代的な手法から抜け出せない開発者がまだ数多く存在する。しかし、プロフェッショナルなチームが目指すべきは、IDEとXdebugが完全同期した、1秒のロスもない高速フィードバックループだ。

特に Xdebug 3 は、単なるマイナーアップデートではない。内部アーキテクチャの根底から見直され、パフォーマンス、設定の簡素化、そしてリモートデバッグの信頼性において、文字通り「別次元のツール」へと生まれ変わった。

本記事では、Xdebug 2から3への移行で何が変わり、なぜ今すぐ設定を刷新すべきなのか。その背後にある技術的背景と、チーム全体の生産性を爆発的に高める実践的設定のすべてをコード付きで解説する。

—

1. なぜXdebug 3なのか？：アーキテクチャの進化とパフォーマンスの真実

まず、Xdebug 2からXdebug 3への移行で最も特筆すべきは 「パフォーマンスの劇的な改善」 である。

Xdebug 2の抱えていた構造的欠陥

Xdebug 2時代、開発者は常に「デバッグを有効にするとアプリケーション全体が重くなる」というジレンマに悩まされていた。Xdebug 2では、デフォルトでコードカバレッジやプロファイリングなどの重い機能がバックグラウンドで常に初期化処理の対象となっており、リクエストごとに莫大なオーバヘッドが発生していた。これが原因で、本番環境はもちろん、ローカルのDocker環境でも「重いから開発時はXdebugをオフにする」という本末転倒な運用が横行していたのだ。

Xdebug 3の「モード」概念による劇的軽量化

Xdebug 3では、この設計思想が180度転換された。「Mode（モード）」 という概念が導入され、明示的に指定した機能以外は完全に無効化（ゼロコストに近い状態）されるようになった。

; 必要な機能だけをカンマ区切りで明示的に有効化する（余計なオーバヘッドを排除）
xdebug.mode = debug,develop

`develop`: 従来の `clieval` や詳細なスタックトレース、改善されたエラー出力などの開発支援機能。
`debug`: ステップデバッグ（ブレークポイント、変数インスペクション）。
`profile`: プロファイリング（Cachegrindファイル出力）。
`coverage`: PHPUnit等でのコードカバレッジ計測（テスト実行時のみ有効化すべき）。

この変更により、デバッグを使わない通常のリクエスト処理において、Xdebug 3はXdebug 2と比較して最大で数倍〜十数倍の高速化を実現している。開発環境であっても、もはや「Xdebugを外す理由」は存在しない。

—

2. 旧設定からの脱却：Xdebug 2 vs 3 設定値の完全対比

Xdebug 3では、設定ディレクティブの命名規則が大幅に整理され、冗長なプレフィックスが排除された。移行時に最も混乱しやすい主要な設定変更を以下に整理する。

特に重要なのは デフォルトポートが `9000` から `9003` に変更された点 だ。Xdebug 2時代、PHP-FPMがデフォルトで `9000` 番ポートを使用していたため、Docker環境などでポート競合を起こし、謎の接続エラーに悩まされた開発者は数知れない。Xdebug 3はこのポートを `9003` に改め、モダンなエコシステムとの調停を図っている。

—

3. 実践：チーム開発を加速する `php.ini` ベストプラクティス構成例

Docker（LEMP/LAMP）環境において、チーム全体でシームレスに動作し、かつパフォーマンスを最大化する `docker/php/conf.d/xdebug.ini` のプロダクション・グレードの構成例を提示する。

; ==============================================================================
; Xdebug 3 Production-Grade Configuration for Containerized Environments
; ==============================================================================

[xdebug]
; 1. 稼働させるモードの定義
; 開発時はステップデバッグ(debug)と詳細エラー表示(develop)のみを有効化。
; カバレッジやプロファイリングは必要時のみ指定し、普段の実行速度を死守する。
xdebug.mode = debug,develop

; 2. IDEへの接続トリガー戦略
; ‘yes’ に設定することで、HTTPリクエストやCLI実行時に常にIDEへ接続を試みる。
; ブラウザ側の拡張機能（Xdebug Helper）やIDEキーとの組み合わせで真価を発揮する。
xdebug.start_with_request = yes

; 3. IDE（ホスト側）のリスナーホストの指定
; Docker Desktop（Mac/Windows）環境ではお馴染みの特殊ホスト名。
; Linux環境の場合はホストのIPアドレスや ‘172.17.0.1’ に書き換えること。
xdebug.client_host = host.docker.internal

; 4. IDEとの通信ポート
; Xdebug 3の標準ポートである 9003 を明示的に指定。
xdebug.client_port = 9003

; 5. ログ出力設定（トラブルシューティングの命綱）
; デバッグが繋がらない原因の9割はネットワーク・パス解決のミスマッチ。
; 接続失敗時のログをファイルに出力させることで、秒速で原因を特定できる。
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 7

> アーキテクトの知見：`xdebug.log` の重要性
> チームメンバーから「デバッグが繋がらない」というチケットが上がった際、上記のようにログ出力パスを固定し、`docker exec -it tail -f /tmp/xdebug.log` を叩かせれば、IDEがコネクションを拒否しているのか、ポートが塞がっているのかが一目で判明する。無駄なチャットのやり取りをゼロにできる。

—

4. 開発スピードを劇的に高める IDE & ツール連携術

ここからが本題だ。Xdebug 3のポテンシャルを100%引き出し、開発速度を極限まで高めるための「神プラグイン」と「キーボードショートカット」の運用術を伝授する。

① 絶対入れるべき神プラグイン（VS Code / PhpStorm共通）

ブラウザ拡張機能：Xdebug Helper (Chrome / Firefox)
ブラウザのツールバーからワンクリックでクッキー（`XDEBUG_SESSION=PHPSTORM` または `VSCODE`）を付与・削除できる。
運用ルール: チーム全員にこの拡張機能を強制し、デバッグが必要な時だけアイコンを「緑（Debug）」に光らせるフローを徹底する。これにより、不要なリクエストブロックを防げる。

② VS Code / PhpStorm でのパス・マッピングの罠と対策

Dockerなどのコンテナ環境で開発する場合、ホスト側のソースコードパスとコンテナ内のパスが一致しないため、ブレークポイントで止まらない現象が多発する。

VS Code (`.vscode/launch.json`) のベストプラクティス設定:

{
“version”: “0.2.0”,
“configurations”: [
{
“name”: “Listen for Xdebug (Docker)”,
“type”: “php”,
“request”: “launch”,
“port”: 9003,
“pathMappings”: {
// コンテナ内の絶対パス : ホスト側のプロジェクトルート絶対パス
“/var/www/html”: “${workspaceFolder}”
},
// ログに出る余計なステップインを防ぐための除外設定
“ignore”: [
“/vendor//.php”
]
}
]
}

サードパーティのライブラリ（`vendor/` 以下）の内部に入り込んで迷子になる時間を、`ignore` 設定によって完全に排除する。ビジネスロジックのデバッグにのみ集中できる環境を作るのがテックリードの仕事だ。

③ 開発効率を異次元にするキーボードショートカット

マウスを使ってIDEのデバッグボタン（再生、ステップオーバーなど）をクリックしている時点で、あなたの開発スピードは半分以下に落ちている。以下のショートカットを頭ではなく「指に覚え込ませろ」。

—

5. チーム開発で絶対に守るべき設定の共有化ルール

個人個人がローカルでバラバラの `php.ini` をいじっているチームは、必ず「私の環境では動くが、あなたの環境ではデバッグできない」という不毛な障害に直面する。これを根絶するためのガバナンスルールを定義する。

1. Xdebugの設定はリポジトリにコードとしてコミットする

Docker環境を採用し、`docker/php/conf.d/xdebug.ini` のような形でバージョン管理システム（Git）に含める。
開発者は `docker compose up –build` を叩くだけで、全員が全く同一のXdebug 3環境を手に入れられるようにする。

2. `xdebug.mode` の運用ルール化

普段の開発時は `debug,develop`。
CI環境や負荷テスト（JMeter / k6等）の実行時は、Xdebugのモードを完全に無効化（`xdebug.mode=off` またはモジュール自体をロードしない）するビルドスクリプトを用意し、ベンチマークの正確性を担保する。

—

結び：ツールを支配する者が、開発速度を支配する

Xdebug 3への移行は、単なるバージョンの数字の置き換えではない。それは、チームの開発プロセス全体から「無駄な待ち時間」と「バグ調査の精神的ストレス」を削ぎ落とすための、極めて合理的かつ投資対効果の高いエンジニアリングである。

古い設定や、重いデバッガの挙動に甘んじる時代は終わった。
本記事で提示した設定とアーキテクチャの知見を即座にチームへ導入し、圧倒的なスピード感で高品質なコードをデリバリーし続けてほしい。