Xdebug接続を傍受せよ：DBGPプロトコルとTCPプロキシによるネットワーク層の極限デバッグ
数多のPHPエンジニアが、ローカル環境やDockerコンテナでのXdebug接続トラブルに直面したとき、「`xdebug.client_host`のIPが違う」「ポートが空いていない」「ファイアウォールが邪魔をしている」という、ネットの海に溢れ返った表層的なトラブルシューティングで時間を溶かしている。
だが、少し考えてみてほしい。
IDE（PhpStormやVS Code）とPHPランタイム上で動くXdebugは、一体どのような言葉を交わしてセッションを確立しているのか？ `connection refused` やタイムアウトという冷徹なエラーコードの裏側で、ネットワークパケットのレイヤでは何が起きているのか？
本稿では、世界最高峰の開発環境アーキテクトとして、DBGP（Debug Protocol）のバイナリ／XMLストリームをTCPプロキシやWiresharkで「傍受」し、プロトコルレベルからデバッグ環境を完全に掌握するための極限知見を授ける。
—
1. 内部アーキテクチャの真実：DBGPプロトコルとTCPハンドシェイクの暗黙の了解
Xdebug（v3以降）とIDEの通信は、IANAで標準化されたTCPポート `9003` を用いた DBGPプロトコル によって行われる。
多くの開発者は「HTTPリクエストがトリガーとなってXdebugがIDEに接続しに行く」と表面的に理解しているが、実際のネットワーク層では以下のような精密なステートマシンが駆動している。
1. HTTPリクエストの侵入: クライアント（ブラウザやcURL）からPHP-FPMまたはCLIへリクエストが到達。
2. トリガーの評価: `xdebug.mode = debug` かつ `xdebug.start_with_request = yes`（または `trigger`）の場合、Xdebugはセッションの初期化を試みる。
3. TCPアクティブオープン（Reverse Connection）: Xdebug（クライアント側）が、`xdebug.client_host` と `xdebug.client_port`（デフォルト9003）に向けてTCP SYNパケットを送信する。つまり、ネットワークの文脈においては、PHPランタイムがクライアントであり、IDEがサーバ（リスナー）である。
4. DBGPハンドシェイク: TCPコネクション確立直後、XdebugからIDEへ初期化XMLパケット（`
この「逆転の構図（PHP側がクライアント、IDE側がサーバ）」を理解していないがために、Docker環境やクラウドIDEにおいて、ルーティングやポートフォワーディングの設計ミスが頻発するのだ。
—
2. 現場でなぜ接続が拒絶されるのか？：パケットレベルの故障診断
IDEが接続を拒絶する、あるいは「デバッグがフリーズする」現象の根本原因は、ログファイルだけを見ても絶対に分からない。TCPプロキシを間に挟み、流れるパケットを生のデータとして観測する必要がある。
観測すべき3つの致命的アンチパターン
- IDEのバインドインタフェースの不一致: IDEが `127.00.0` にしかバインドしていない状態で、Dockerコンテナのブリッジネットワーク（例: `172.17.0.1`）から接続が来ると、カーネルレベルで `RST` パケットが返される。
- 初期化XMLのパースエラー: 巨大なフレームワーク（SymfonyやLaravel）の初期化時に、Xdebugが送信する初期化XMLのサイズがIDE側のバッファ上限を超える、あるいはマルチバイト文字の不整合でDBGPパーサーがクラッシュする。
- タイムアウトの競合: `xdebug.connect_timeout_ms`（デフォルト200ms）の間にIDEがACKを返せないほどのネットワーク遅延（Kubernetesクラスター間やVPN経由）が存在する。
—
3. 実践：TCPプロキシ（`socat` / `mitmproxy`）によるDBGP通信の傍受
ここでは、Dockerコンテナ環境とホストOSの間に軽量なTCPプロキシを挟み込み、XdebugとIDEの間でやり取りされるDBGPの生データをすべてファイルおよび標準出力にキャプチャするアーキテクチャを構築する。
アーキテクチャ図
[ PHP / Xdebug (Container) ]
│ (TCP 9003)
▼
[ TCP Proxy (socat on Host: 9003) ] ──(ログ記録・パケット解析)──>
│ (TCP 19003)
▼
[ IDE / PhpStorm (Host: 19003) ]
ステップ1: プロキシの起動（`socat` の活用）
ホストOS上で、Xdebugからの接続を待ち受け、それをIDEの本当の待ち受けポートへ転送しつつ、全送受信データをHex/ASCIIでダンプする `socat` コマンドを実行する。
役割: TCPポート9003で待ち受け、受信したDBGPストリームを標準エラー出力にHEX/ASCIIダンプしながら、
ホスト側IDEが待機しているポート19003へフォワードする。
socat -v \
TCP-LISTEN:9003,fork,reuseaddr \
TCP:127.0.0.1:19003
> アーキテクトの知見: `-v` オプションにより、stderrに `> `（XdebugからIDEへ）と `< `（IDEからXdebugへ）の方向を示すプレフィックス付きで通信内容が完全に出力される。これにより、どちらのレイヤでプロトコル違反が起きているかが一目瞭然となる。
ステップ2: Xdebug側の設定（`php.ini`）
プロキシ（ホストの9003ポート）を指すようにXdebugを設定する。Docker環境の場合は、ホストを指す特別なIP（Linuxなら `172.17.0.1` や `host.docker.internal`）を指定する。
[xdebug]
; 必須: Xdebugの稼働モードをdebugに指定
xdebug.mode = debug
; 自動スタート（すべてのリクエストでデバッグを試みる。高負荷環境ではtriggerを推奨）
xdebug.start_with_request = yes
; 宛先を「socatプロキシが稼働しているホストIP」に向ける
xdebug.client_host = host.docker.internal
; socatが待ち受けているポートを指定
xdebug.client_port = 9003
; ネットワーク遅延やプロキシ経由のデバッグを考慮してタイムアウトを延長（極限環境向け）
xdebug.connect_timeout_ms = 2000
—
4. 傍受されたDBGPパケットの解読：プロトコルアナライザの眼
`socat` や Wireshark（ディスプレイフィルタ: `tcp.port == 9003`）でキャプチャしたストリームには、以下のようなDBGP生データが流れている。
送信される初期化XMLの例（Xdebug ➔ IDE）
IDEからの応答コマンドの例（IDE ➔ Xdebug）
feature_set -i 1 -n show_hidden -v 1\0
もしIDEが接続を拒絶（あるいはハング）する場合、このXMLの `fileuri` のパスがIDE側のプロジェクトパスと完全に一致しているか（パスのマッピングが正しく機能しているか）、あるいはIDEが返すべき `feature_set` に対する応答（`
—
5. CI/CDパイプラインとローカル環境を完全自動化するDevOpsハック
手動で `socat` を立ち上げるような非効率な運用は、我々の流儀ではない。Docker Compose環境において、開発者全員が意識することなくデバッグプロキシとパケットロギング層を統合するためのインフラコードを提示する。
`docker-compose.override.yml` によるデバッグプロキシのサイドカー構成
version: ‘3.8’
services:
# デバッグ対象のPHPアプリケーションコンテナ
app:
environment:
# Linux環境のDockerにおいてホストへ確実にルーティングするためのマジックIP
- XDEBUG_CONFIG=client_host=172.17.0.1 client_port=9003
extra_hosts:
- “host.docker.internal:host-gateway”
# アーキテクト特製: DBGPパケットを自動傍受・ロギングするサイドカープロキシサービス
dbgp-proxy:
image: alpine/socat:latest
container_name: xdebug_proxy_inspector
# 役割: コンテナ外部からの9003ポートへの接続を受け付け、ホストのIDEリスナーへ転送しつつログを永続化
command: [
“-v”,
“TCP-LISTEN:9003,fork,reuseaddr”,
“TCP:host.docker.internal:19003”
]
ports:
- “9003:9003”
extra_hosts:
- “host.docker.internal:host-gateway”
restart: always
この構成を導入することで、開発者はIDE側のリスニングポートを `19003` に設定するだけで、コンテナとIDEの間で行われるすべてのDBGP通信が `docker logs xdebug_proxy_inspector` を通じて完全に可視化され、CI環境やステージング環境でのリモートデバッグのトラブルシューティング工数をゼロに収束させることが可能となる。
—
結び：ツールに依存するな、プロトコルを支配せよ
GUIの「デバッグボタン」を押して動かないと嘆く時代は終わった。
真のエリートエンジニアは、アプリケーションと開発ツールの間に流れるパケットの1ビットに至るまでを支配する。TCPプロキシを用いた通信の傍受手法を手に入れたあなたにとって、もはや「なぜか動かないデバッグ」という概念は存在しない。あるのは、論理的に解決可能なネットワーク上の事実だけだ。
この知見をあなたの開発パイプラインに組み込み、圧倒的なスピードでコードの深淵を暴き出してほしい。