IDEの呪縛を解き放て：CLIとDBGpプロトコルで操る、真のXdebugマスタークラス
テックリードの佐藤だ。
おっと、あなたのプロジェクトでは、いまだに「Xdebugを使うために、わざわざ数GBの重厚長大なIDEを立ち上げ、複雑なGUIのブレークポイント設定に神経をすり減らしている」わけじゃないよな？
Dockerコンテナが当たり前になり、サーバーレスやマイクロサービス全盛の現代において、GUIデバッガへの依存は開発生産性を大きくスポイルするボトルネックでしかない。本番同等の軽量なコンテナ環境、あるいはCI/CDパイプラインの途中で突発的に発生したCLIスクリプトのバグ。そんな時、手元にあるのはSSHの黒い画面と、使い慣れたVimやNeovim、あるいはNanoだけだとしたらどうする？
今回は、IDEという巨大な免罪符を完全に剥ぎ取り、コマンドラインから直接Xdebugのセッションを制御し、DBGpプロトコルの生データと対話するプロフェッショナルな手法を伝授する。これを知れば、あなたのデバッグスピードは次元の違う領域へと加速するはずだ。
—
1. そもそもXdebugとIDEの裏側で何が起きているのか？（DBGpプロトコルの真実）
「PHPでブレークポイントを張る」という魔法のような現象は、魔法でも何でもない。PHPの実行エンジン（Zend Engine）に組み込まれたC拡張であるXdebugと、それを待ち受けるデバッグクライアント（IDE等）が、TCPソケットを介してDBGp（Debug Protocol）という標準化されたXMLベースのプロトコルで対話しているだけなのだ。
通常、IDEはこの通信を隠蔽し、リッチなUIでラップしてくれている。しかし、プロトコルの実態を理解していけば、`netcat`や専用のCUIクライアントさえあれば、人間が直接デバッガを操作できることに気づく。
デバッグセッション確立のシーケンス
1. トリガー（Trigger）: リクエストパラメータ（`XDEBUG_SESSION_START=1`）やCLI環境変数（`XDEBUG_TRIGGER=1`）により、Xdebugが起動。
2. 接続（Connection）: Xdebugが設定されたIPとポート（デフォルトは `127.0.0.1:9003`）へTCPソケット接続を試みる。
3. 初期化（Init Packet）: Xdebugからクライアントへ、PHPのバージョンやIDEキーを含むXMLパケットが送信される。
4. 対話（Interaction）: クライアントから `breakpoint_set` や `run`、`step_over` といったDBGpコマンドを送信し、エンジンの状態を操作する。
この仕組みさえ分かれば、「IDEがないからデバッグできない」という言い訳は完全に消え去る。
—
2. 開発スピードを劇的に高めるCLIデバッグツール群
IDEなしでXdebugを使い倒すために、現場のプロたちがこっそり使っている神ツールと、その実践的な操作術を紹介する。
① `vibe/dbgp` または Python製CUIデバッガの導入
フル機能のIDEを使わずとも、ターミナル上で対話的にステップ実行ができるCUIデバッガが存在する。Python製の `dbgpClient` や、よりモダンなコマンドラインツールを活用しよう。
② 環境変数によるセッションの完全制御
CLIでスクリプトを実行する際、毎回コマンドに引数を渡すのはナンセンスだ。シェル環境変数としてXdebugの挙動を完全にコントロールする。
.bashrc または .zshrc に記述するプロフェッショナルなスニペット
export XDEBUG_MODE=debug
export XDEBUG_TRIGGER=1
export XDEBUG_SESSION=CLI_DEBUG
export XDEBUG_CLIENT_HOST=127.0.0.1
export XDEBUG_CLIENT_PORT=9003
この設定を行った上で、以下のコマンドを実行するだけで、即座にXdebugは指定ポートへ接続要求を飛ばすようになる。
php artisan command:process-queue –no-interaction
—
3. 実用的な設定ファイル（php.ini / docker-compose.yml）のベストプラクティス構成例
チーム開発において、ローカル環境でもコンテナ環境でも、Xdebugの設定がバラバラでは話にならない。インフラとアプリケーションの境界をシームレスに繋ぐ、極限まで最適化された設定ファイルの構成案を公開する。
構成例1: `docker-compose.yml`（アプリケーションサービス定義）
コンテナ内からホストマシンのデバッグクライアント（またはCUIリスナー）を正確に捕捉するためのネットワーク設定と、Xdebug 3に最適化した環境変数インジェクション。
version: ‘3.8’
services:
app:
build:
context: .
dockerfile: docker/php/Dockerfile
volumes:
- .:/var/www/html:cached
environment:
# Xdebug 3のモード指定（debugとprofilerを同時に有効化しないのがパフォーマンスの鉄則）
- XDEBUG_MODE=debug
- XDEBUG_START_WITH_REQUEST=yes
# Dockerホストの自動解決（Linux環境におけるhost.docker.internalのフォールバックを含む）
- XDEBUG_CLIENT_HOST=host.docker.internal
- XDEBUG_CLIENT_PORT=9003
extra_hosts:
- “host.docker.internal:host-gateway”
networks:
- backend-net
networks:
backend-net:
driver: bridge
構成例2: `php.ini`（Xdebug 3 本番・開発共通最適化設定）
ローカル開発環境（Docker内）にマウントする `xdebug.ini` の決定版。無駄なオーバーヘッドを排除しつつ、CLIでのデバッグ体験を最大化する。
[xdebug]
; 拡張モジュールのロード（環境によりパスは異なるが通常は自動ロード）
zend_extension=xdebug.so
; 開発環境に必要なモードのみを有効化（パフォーマンス劣化を防ぐ）
xdebug.mode = debug
; スクリプト開始時に自動的にデバッグ接続を試みる（CLIでの即座のデバッグに必須）
xdebug.start_with_request = yes
; クライアント（ホスト側）のIPアドレスまたはホスト名
xdebug.client_host = host.docker.internal
; Xdebug 3の標準ポート
xdebug.client_port = 9003
; ログ出力設定（接続トラブル時のライフライン。必ず書き込み可能なパスを指定）
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 7
; 例外発生時に自動的にブレーク（スタックトレースを即座に取得するため）
xdebug.show_exception_trace = 0
xdebug.remote_connect_back = 0
—
4. チーム開発で役立つ設定の共有化ルール
「私のローカルではデバッグできるのに、あの人の環境では動かない」——この不毛なトラブルをチームから根絶するためのルールメイク。
1. `XDEBUG_MODE` のデフォルトは `off` にする（本番・ステージング）
本番環境で誤って `xdebug.mode=debug` が有効化された場合、すべてのリクエストでTCPソケットのタイムアウトが発生し、アプリケーションが壊滅的なスローダウンを引き起こす。環境変数またはDockerイメージのビルド引数で厳格に分離すること。
2. `xdebug.client_host` には `host.docker.internal` またはマジックIPを使用する
IPアドレスをハードコーディングすると、OSが異なるメンバー（Mac / Windows / Linux）で必ず破綻する。Dockerの `host-gateway` 機能を活用し、プラットフォーム非依存の接続性を担保する。
3. 接続ログの監視を習慣化する
トラブルシューティングの第一歩は `/tmp/xdebug.log` を監視することだ。以下のコマンドを叩くだけで、Xdebugがどこに接続しようとして弾かれているのかが一目瞭然になる。
tail -f /tmp/xdebug.log
—
5. 実践：ネットキャット（nc）だけでDBGpプロトコルと対話する
最後に、IDEというブラックボックスを取り払った世界を体験しよう。Netcatを使い、TCPポート `9003` でXdebugからの接続を直接待ち受け、コマンドを手打ちしてデバッグを進める手順だ。
ステップ1: ターミナルでポートをリスンする
nc -l 9003
ステップ2: 別ターミナルでCLIスクリプトを実行する
先ほど設定した環境変数を有効にした状態でPHPスクリプトを実行する。
php -d xdebug.mode=debug -d xdebug.start_with_request=yes script.php
ステップ3: 接続確立とDBGpコマンドの送信
スクリプトが実行されると、最初のターミナル（`nc`）に以下のようなXMLパケットが飛び込んでくる。
ここに、手動でDBGpのコマンド（トランザクションID付き）を送信することで、プログラムの実行を意のままにコントロールできる。
- スクリプトの実行を継続する（Run）:
feature_set -i 1 -n show_hidden 1
(※返却されるXMLレスポンスを解釈し、ブレークポイントやステップ実行を指示する)
—
テックリードからの総括
IDEのGUIボタンをクリックするだけの開発者は、ツールが提供する便利さと引き換えに、システム内部で何が起きているのかという「エンジニアリングの本質」を徐々に失っていく。
今回紹介したCLIとDBGpプロトコルをベースにしたデバッグ手法は、単なる「軽量環境での代替手段」ではない。コンテナのトラブルシューティング、CI環境での高度なインスペクション、そして何より「コンピュータの挙動を完全に支配している」という確かなエンジニアリングの自信をあなたにもたらすものだ。
明日からの開発で、ぜひこの黒い画面からのデバッグを試してほしい。あなたのコード品質とトラブル解決スピードは、間違いなく次のステージへと引き上げられるはずだ。