【実務・中級編】Xdebugの「xdebug.remote_log_level」を活用した、間欠的なコネクション切断のデバッグ術 – デバッグ・コード品質・テストツール生産性向上バイブル

Xdebugの「見えない切断」をねじ伏せる：DBGpプロトコルと`xdebug.remote_log`（現行`xdebug.log`）によるコネクション解析の極意

テックリードの〇〇です。

日々のPHPアプリケーション開発において、複雑なビジネスロジックや非同期処理、あるいは重厚なフレームワークのライフサイクルを追う上で、Xdebugによるステップデバッグはもはや呼吸をするのと同じくらい不可欠なインフラストラクチャです。

しかし、あなたもこんな経験はないでしょうか？
「ブレークポイントで処理が止まり、変数のスコープを吟味しようと数秒（あるいは数分）考え込んでいると、突然IDEとPHPの接続がプツリと切れ、ページがそのままレスポンスを返して実行完了してしまう」

この「間欠的なコネクション切断（Intermittent Connection Drop）」は、開発者の思考のフローを完全に破壊し、デバッグ効率を地の底まで落とします。多くのエンジニアはこれを「IDEの気まぐれ」や「Docker環境のネットワークの不調」として片付けがちですが、それはエンジニアリングの放棄です。

今回は、Xdebugの内部通信プロトコルである DBGp（DBGp Proxy / Protocol） のハンドシェイクの裏側を暴き、`xdebug.log`（旧`xdebug.remote_log`）のログレベルを極限まで引き上げて「切断の真犯人」を特定・完全鎮圧するプロフェッショナルなデバッグ術を伝授します。

—

1. なぜ接続は切れるのか？：DBGpプロトコルの裏側

XdebugとIDE（PhpStormやVS Codeなど）の通信は、DBGpというプロトコルに基づいてTCPソケット上でやり取りされます。

大まかなライフサイクルは以下の通りです。
1. HTTPリクエストの検知: PHPがリクエストを受け取り、Xdebugが起動条件（`xdebug.mode=debug`等）を満たしているかを判定。
2. TCPコネクション確立: Xdebug（クライアント側）が、指定されたIPとポート（デフォルトは `9003`）に向かってIDE（リスナー側）へTCPコネクションを張る。
3. 初期化ハンドシェイク: `init` XMLパケットが送られ、IDEがセッションID、IDEキー、PHPのバージョンなどのメタデータを受け取る。
4. インタラクション: ユーザーが「ステップオーバー」「変数の評価」などのコマンド（`stack_get`, `context_get` など）を送信し、XdebugがXMLレスポンスを返す。

ここで問題になるのが、「ステップ3と4の間の沈黙（Idle Time）」です。
IDE側（特にPhpStormなど）や、Docker/WSL2などの仮想ネットワーク層、さらにはホストOSのファイアウォールには、無通信状態が一定時間続いた場合にソケットを強制切断する「キープアライブ（Keep-Alive）タイムアウト」が存在します。

人間がブレークポイントで止まった画面を見ながら「さて、この配列の構造はどうなっているんだっけ…」と30秒ほど思考にふけっている間に、ネットワーク層が「このTCPコネクションは死んでいる」と誤認し、RSTパケットを送りつけて接続をブチ殺しているのです。

この「目に見えないタイムアウト」を科学的に観測するために、Xdebugのロギング機能を極限まで活用します。

—

2. ログレベルを最大化する：`xdebug.log` の設定と読み解き

Xdebug 3以降では、リモート・通信ログの設定ディレクティブが統合・洗練されました。接続切断の真の原因を究明するためには、ログレベルを `7`（最も詳細なデバッグ情報）に設定し、すべての通信パケットと内部ステータスをファイルに出力させる必要があります。

実用的な `php.ini` / `docker-php-ext-xdebug.ini` のベストプラクティス

チーム全体でこの設定を共有することで、環境差異によるデバッグの属人性を完全に排除できます。

[xdebug]
; デバッグモードを有効化（ステップデバッグ、プロファイル等の機能選択）
xdebug.mode = debug

; リクエスト毎に自動でデバッグを開始せず、トリガー（クエリパラメータやCookie）がある場合や明示的なブレークポイントで発火
xdebug.start_with_request = yes

; IDEが待ち受けているホストのIP（Docker環境の場合はホストを指す特殊なIPやホスト名を設定）
xdebug.client_host = host.docker.internal

; IDE側のリスニングポート（Xdebug 3からはデフォルトで9003）
xdebug.client_port = 9003

; 【最重要】通信ログの出力先パス（コンテナ内であってもホストからマウントされたボリューム上、または標準出力に出すのが吉）
xdebug.log = /var/log/xdebug/xdebug.log

; 【最重要】ログの冗長性レベル
; 0: エラーなし, 1: コネクションエラーのみ, 3: 接続情報, 5: 通信プロトコルメッセージ, 7: すべての内部デバッグ情報（タイムスタンプ付き）
xdebug.log_level = 7

—

3. ログ解析実践：切断の瞬間をキャプチャする

実際に `xdebug.log_level = 7` を設定した状態で、デバッグ中に接続が切断された際のログ（実例の抜粋）を見てみましょう。

[12345] I: Time: 202X-10-25 10:15:00.123456
[12345] I: Connecting to client ‘host.docker.internal:9003’.
[12345] I: Connected to client.
[12345] P: -> Derick Rethanshttp://localhost/my-projectfile:///app/public/index.phpstate=”enabled”>

[12345] P: <- feature_get -i 1 -n support_stop_on_entry [12345] P: ->

; — ここから思考タイム（無通信状態が続く） —

[12345] W: Timeouts: send/recv failed on socket: Resource temporarily unavailable (or Connection reset by peer)
[12345] I: Connection closed.

ログから読み解くべき3つのポイント

1. `P: ->` と `P: <-`: それぞれXdebugからIDEへの送信（送信XML）、IDEからXdebugへの受信コマンドを示しています。このパケットの往復が途絶えたタイミングを確認します。
2. `Resource temporarily unavailable` または `Connection reset by peer`: OSのソケットレイヤーがタイムアウトした際の典型的なエラーメッセージです。
3. タイムスタンプの間隔: 最後のコマンドから切断エラーまでの経過時間（秒数）を確認し、それがDocker Desktop、WSL2、あるいはPhpStormのどのタイムアウト設定と一致するかを逆算します。

—

4. チーム開発の生産性を底上げする「神設定」と共有化ルール

個人のローカル環境ごとに設定がバラバラだと、「私の環境ではデバッグできるのに、あの人の環境ではすぐに切れる」という不毛な議論が発生します。これを防ぐためのチーム共有ルールと設定を提示します。

A. PhpStorm側の設定チューニング（IDE側の防衛策）

PhpStorm側でも、無通信によるタイムアウトを防ぐ設定を行います。
1. `Settings` (または `Preferences`) -> `PHP` -> `Debug` を開く。
2. `Max. simultaneous connections` や `Connection timeout` の設定を確認。
3. 接続が切れる現象を防ぐために、PhpStormの内部デバッグサーバーのタイムアウト値を拡張する（※PhpStorm 2023以降では自動キープアライブが強化されていますが、念のためIDEのバックグラウンドタスクがCPUを食いつぶしてフリーズしていないかも確認）。

B. 開発スピードを限界突破させる PhpStorm ショートカット

デバッグ中の操作スピードは、開発の「フロー状態」を維持するために極めて重要です。マウスを触っている時点で負けです。以下のショートカットを指に叩き込んでください。

C. 必須プラグイン：`Xdebug Profiler` / `Docker` インテグレーション

PhpStorm Docker Integration: コンテナ内のパスとホスト側のパスのマッピング（Path Mappings）を完璧に同期させ、「ファイルが見つからない」というパケットエラーを根絶します。

—

5. まとめ：トラブルシュートを「再現性のある科学」に昇華せよ

「デバッグが途中で切れる」という現象は、単なる運や環境の悪さではありません。DBGpプロトコルという厳格なTCP通信の仕様と、それを囲むネットワーク・OSレイヤーのタイムアウト値のミスマッチによって引き起こされる、極めて論理的な現象です。

今回紹介した `xdebug.log_level = 7` を駆使したログ解析のプロセスをチームに導入すれば、感覚的なトラブルシューティングから脱却し、インフラストラクチャレベルで問題を秒速で解決できるようになります。

あなたのチームの開発スピードを、今日、この瞬間から一段上のステージへと引き上げてください。