【入門編】IDEなしでもXdebugは使える！コマンドラインからデバッグセッションを開始する実用コマンド集 – デバッグ・コード品質・テストツール生産性向上バイブル

こんにちは！日々のPHP開発、お疲れ様です。
「PHPのデバッグといえば、PhpStormやVS CodeなどのリッチなIDE（統合開発環境）を使うもの」――そう思い込んでいませんよね？

もちろんIDEは素晴らしいツールですが、例えば「本番同等の重厚なDockerコンテナ環境」「SSHで接続したリモートサーバー」「CI/CDのパイプライン上」、あるいは「ちょっとしたCronのCLIスクリプト」といった状況では、IDEのGUIが使えない、あるいは設定が複雑すぎて心が折れそうになることがあります。

実は、Xdebugの本質は「DBGpという通信プロトコルを喋るサーバー」であり、IDEはそのクライアントに過ぎません。つまり、仕組みさえ理解してしまえば、コマンドラインだけでも、さらには「何も特別なツールを入れずとも」、デバッグセッションを自在にコントロールできるようになるのです。

今回は、IDEなしでXdebugをしゃぶり尽くし、どんな環境でも一瞬でバグの原因を特定できるようになる「実用コマンド集」を、優しく丁寧にお伝えします。これをマスターすれば、あなたのデバッグスピードは文字通り桁違いに速くなりますよ。

—

1. Xdebugの根底にある「DBGpプロトコル」の仕組み

まず、ツールを使わないデバッグを行うために、Xdebugが裏側で何をしているのかをざっくりと把握しておきましょう。

Xdebugは、PHPの実行を一時停止させたり、変数の値を除いたりするために DBGp（Debugging Protocol） というプロトコルを使用します。この通信の流れは非常にシンプルです。

1. トリガー（Trigger）: HTTPリクエストやCLIの実行時に、環境変数やパラメータで「デバッグしてね」と合図を送る。
2. 接続（Connection）: Xdebug（サーバー）が、設定されたIPとポート（デフォルトは `9003`）に向けて、外の世界（あなた）に逆接続（リバースコネクション）を試みる。
3. 対話（Interaction）: 接続が確立されると、テキストベースのコマンド（ステップ実行、変数の取得など）をやり取りする。

つまり、「自分がDBGpクライアントになって、Xdebugからの接続を受け止め、コマンドを叩けばいい」わけです。

—

2. 最小限かつ最強の「基礎セットアップ」

まずは、余計なGUIを排除し、CLIでのデバッグを確実に行うための `php.ini` の設定を行いましょう。環境によって読み込むファイルが異なりますが、Xdebug用の設定ファイル（例: `99-xdebug.ini`）に以下を記述します。

[xdebug]
; Xdebug 3以降の必須モード指定。ステップデバッグを有効化
zend_extension=xdebug
xdebug.mode=debug

; リクエストがあったら自動的にデバッグを開始する（CLIデバッグでは超重要）
xdebug.start_with_request=yes

; Xdebugが接続しに行くクライアントのIP（通常はホストマシンを指す localhost）
xdebug.client_host=127.0.0.1

; IDEが待ち受けているポート（デフォルトは9003）
xdebug.client_port=9003

; ログを出力して接続エラー時の原因追跡を容易にする（トラブルシューティングの命綱）
xdebug.log=/tmp/xdebug.log

この設定のミソは `xdebug.start_with_request=yes` です。これにより、CLIからPHPスクリプトを叩いた瞬間、Xdebugは強制的に `client_host:client_port` へ接続を試みるようになります。

—

3. IDEなしで動かす！「HelloWorld」的な動作確認

それでは、実際にIDEを使わずにXdebugのセッションをキャッチしてみましょう。
ここでは、最も身近にあるツールである `netcat`（または `nc` コマンド）を使って、Xdebugが生で発するDBGpの生データ（メッセージ）を覗いてみます。

ステップ1: ターミナルでポートを待ち受ける

まず、1つ目のターミナルを開き、Xdebugが飛んでくるポート（9003番）をリッスンします。

-l: 待ち受けモード, -v: 詳細表示, -p: ポート指定
nc -lvp 9003

※Macの場合は `nc -v -l 9003` など、OSのnetcatの仕様に合わせて調整してください。

ステップ2: 別ターミナルからCLIスクリプトを実行する

次に、別のターミナルを開き、適当なPHPスクリプトを実行します。ここでは、あえてエラーや変数の確認を含んだ `test.php` を用意しましょう。

test.php:

ステップ3: 通信のキャッチを確認する

スクリプトを実行した瞬間、ステップ1で待ち受けていたターミナル（netcat）に、何やらXMLのような文字列がドバッと表示されるはずです！

Xdebug - Debugger and Profiler Tool for PHP

Xdebug: A powerful debugger for PHP

おめでとうございます！これがDBGpプロトコルの「初期化パケット」です。
PHPの実行がXdebugによって完全に一時停止され、「ねえ、私はここにいるよ。次のコマンドはどうする？」とあなた（クライアント）に語りかけてきている状態です。

—

4. 現場で役立つ！実用CLIデバッグツール・コマンド集

生のエディタやnetcatでXMLを解読するのはさすがに修行僧の領域ですよね。
ここからは、実務の現場でIDEなしでも快適にデバッグを行うための、より実用的なアプローチとコマンド集をご紹介します。

① `vibe` や専用CLIデバッガーを使う

世の中には、CUI（ターミナル内）で動くDBGpクライアントが存在します。その代表例が `dbgpClient` や Python製のデバッガーなどです。

例えば、公式が提供しているシンプルなコマンドラインクライアントや、Node.js製のツールを使えば、ターミナル上で `step_over` や `eval` が実行できるようになります。

② クイックに変数を覗き見したいだけのときの「`xdebug_break()`」

「わざわざ通信を待ち受けるのも面倒だけど、この行の変数の状態だけピンポイントでコンソールに出したい」
そんな時は、コード内に直接ブレークポイントを埋め込める関数 `xdebug_break()` が使えます。

1, ‘name’ => ‘Taro’];

// この記述だけで、接続先（リスナー）があれば自動でコードの実行が中断する
if (function_exists(‘xdebug_break’)) {
xdebug_break();
}

var_dump($user);

これを使うと、コードの意図した箇所だけを正確にキャッチして対話モードに持ち込むことができます。

—

5. 発展編：複雑な環境を救う「デバッグプロキシ（Debug Proxy）」

実務では、次のような複雑な壁にぶつかることがあります。

「Dockerコンテナ内のPHPから見て、開発者のローカルPCのIPが動的に変わる・または複数人で同じ開発サーバーを共有している」
「どのリクエストが誰のデバッグセッションなのかルーティングしたい」

こういう時に登場するのが Xdebug デバッグプロキシ（`xdebug.idekey` とプロキシサーバーの組み合わせ） です。

デバッグプロキシの概念

[PHP / Docker Container]
│ (Xdebug リバース接続)
▼
[デバッグプロキシサーバー (中継地点)]
│ (IDEKeyでルーティング)
├──> [開発者AのPC / IDE]
└──> [開発者BのPC / CLIツール]

プロキシ利用時の設定例 (`php.ini`)

複数のメンバーで同じステージング環境やリモートコンテナをデバッグする場合、プロキシを経由させることで、接続の混線を防ぎます。

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes

; 直接自分のPCを指定するのではなく、プロキシサーバーのIPを指定する
xdebug.client_host = 192.168.10.50 ; プロキシサーバーのアドレス
xdebug.client_port = 9003

; 誰のセッションかを識別するためのユニークな鍵
xdebug.idekey = “MY_UNIQUE_DEV_KEY”

これにより、チーム開発において「自分がデバッグしたいリクエストだけを自分のターミナルやIDEで拾う」という高度なルーティングが可能になります。コンテナ環境のトラブルシューティングにおいて、これを知っているといないとでは解決スピードが文字通り10倍変わります。

—

おわりに：IDEに縛られない自由を手に入れよう

今回は、IDEのGUIに頼らず、XdebugとDBGpプロトコルの仕組み、そしてコマンドラインを使った実用的なデバッグ手法を解説しました。

「IDEが重い・動かない環境でも、CLIでデバッグセッションを張れる」
「ネットワーキングの仕組みが分かっているので、Dockerやリモートコンテナの接続エラーで迷子にならない」
「`xdebug_break()` や `netcat` を通じて、ツールの裏側で何が起きているかを解像度高く理解できる」

これらの知識は、単なる「デバッグのテクニック」にとどまらず、あなたのインフラやミドルウェアに対する総合的なエンジニアリング力を底上げしてくれます。

「道具に使われる側」から「道具を使いこなす側」へ――。
ぜひ、明日の開発からこのコマンドや仕組みを試してみてください。あなたのコーディングライフが、より快適でエキサイティングなものになることを応援しています！