Xdebug の使い方

Xdebug は PHP の拡張機能（エクステンション）です。 Windows の場合は .dll ファイルになります。

公式サイトのダウンロードページから、環境にあった .dll ファイルをダウンロードします。 ベータ版もありますが、ちゃんと動きませんので、安定版（beta とついていないもの）がオススメです。 間違ったバージョンをダウンロードしてしまうと動きませんので注意してください。

.dll ファイルがダウンロードできたら、その .dll ファイルを PHP の拡張機能として読み込むよう設定します。

• まず、ダウンロードした .dll ファイルを PHP のエクステンションディレクトリ（"C:\xampp\php\ext"）に移動させます。

• ファイル名を "php_xdebug.dll" に変更します（つまり、"C:\xampp\php\ext\php_xdebug.dll" とします）。

• 次に、php.ini ファイルを編集し、zend_extension=xdebug の行を追加します。 この際、zend_extension=opcache の行より下に追加するようにしてください。

  php.ini

  zend_extension=xdebug
  

• 最後にWebサーバーを再起動します。

Xdebug がインストールできたら、phpinfo() に Xdebug の情報が追加で表示されていますので確認してみましょう。

xdebug_info() 関数

ちなみに、Xdebug がインストールされると、Xdebug の情報を表示する関数、xdebug_info() も使用できるようになっています。 phpinfo() にも同様の内容が表示されていますが、phpinfo() には他の情報も大量に表示されていますので、 Xdebug だけの情報が知りたい場合は xdebug_info() の方が見やすいと思います。

どの機能が有効になっているかは、phpinfo() や xdebug_info() を表示した際に、「Enabled Features」欄に表示されているので、そこでも確認できます。

条件を満たしたHTTPリクエストの場合のみ開始される設定がトリガーです。 トリガーの条件は、$_ENV、$_GET、$_POST、$_COOKIE のいずれかに XDEBUG_TRIGGER という名前の値があることです。

古いバージョンの Xdebug では、XDEBUG_TRIGGER の代わりに、 XDEBUG_SESSION（ステップ実行用）、XDEBUG_PROFILE（プロファイリング用）、XDEBUG_TRACE（関数トレース用）が使用されていたため、 互換性のためそれらも使用することができるようです。

https://example.com/hoge/hoge?XDEBUG_TRIGGER

Cookie をトリガーにする

GETパラメーターをトリガーにする方法は簡単ではありますが、画面遷移が必要な場合や Ajax などを使用している場合は難しくなってきます。 リンクやボタンをクリックするたびに必要になるのですから、それは面倒になってくると思います。 しばらくの間、続けてトリガーさせるためには、Cookie（$_COOKIE）からトリガーさせた方が楽です。 そのためのWebブラウザの拡張機能がありますので、それを使うと便利です。

• Xdebug Helper for Chrome
• Xdebug Helper for Firefox
• XDebugToggle for Safari

VS Code の設定で必要なことは下記の2つです。

拡張機能「PHP Debug」をインストール

Xdebug はWebサーバー上で動いていますので、VS Code は通信を行う必要があります。 そのため、VS Code に拡張機能を追加する必要があります。この拡張機能が Xdebug と通信してくれます。 Xdebug の公式でオススメされてるのは Felix Becker さんの「PHP Debug」という拡張機能です。 拡張機能の検索欄に「php debug」と入力して検索しインストールします。 同じ名前の拡張機能がたくさんあるので間違えないよう注意です。

launch.json を作成する

launch.json が無い場合は作成します。無い場合は自動で作ってくれます。

手動で編集する場合は、下記の内容にします。 プルダウンの「構成の追加」から「PHP: Listen for Xdebug」を選択して追加したのと同じ内容です。

launch.json

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

VS Code の拡張機能「PHP Debug」のドキュメントには、xdebug.start_with_request を yes とし、全てのHTTPリクエストで開始するよう Xdebug を設定すると記載されていますが、これは必須ではありません。 yes としてしまうと、ステップ実行機能以外の他の機能の開始タイミングにまで影響が出てしまうので注意してください（他の機能を使わないということであれば yes で問題はありません）。

ステップ実行機能の開始タイミングはデフォルトではトリガーです。 ステップ実行時のHTTPリクエストでトリガーできてれば良いだけです。 ブラウザに Xdebug の拡張機能を入れている場合は、Cookie でトリガーさせるのは簡単にできると思いますので、xdebug.start_with_request は default のままで問題ありません。 本当に必要なことは、モードを有効にすることだけです。

[xdebug]
xdebug.mode=debug

あまり他の機能を使わず、ブラウザに Xdebug の拡張機能を入れるのが面倒で、常にステップ実行できる状態としたいのであれば、xdebug.start_with_request を yes としても問題ありません。 用途に合わせて設定しましょう。

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

準備できたので実際にやってみます。 流れは下記になります。

• VS Code で、一時停止させたい個所にブレークポイントを付ける
• VS Code で、デバッグを開始（F5）する。その際、launch.json に作成した「Listen for Xdebug」を使用する
• Webブラウザの Xdebug の拡張機能で、ステップ実行（Debug）のトリガーを有効にする
  （xdebug.start_with_request が yes の場合は不要）
• Webブラウザで、ブレークポイントを付けた個所のURLにアクセスする

PHP の組み込み var_dump() 関数の出力がHTML形式に変更され色が付くようになります。 また、呼び出し場所のファイル名と行番号が含まれるようになります。

C:\Users\Test\develop.php:22:
array (size=4)
  'one' => string 'a somewhat long string!' (length=23)
  'two' =>
    array (size=2)
      1 => int 1
      2 => int 2
  'three' =>
    array (size=1)
      'foo' => string 'bar' (length=3)
  'four' =>
    object(Test)[1]
      public 'pub' => boolean false
      private 'priv' => boolean true
      protected 'prot' => int 42

[xdebug]
xdebug.mode=develop
xdebug.var_display_max_data=512
xdebug.var_display_max_children=128
xdebug.var_display_max_depth=3

Notice、Warning、Error、例外発生時に、スタックトレースが表示されるようになります。 スタックトレースには、スクリプトの開始からエラーが発生した場所までの間に呼び出されたすべての関数とメソッドのリストが含まれています。

開発ヘルパー機能が有効になっている場合のみ使える関数があります。 主にどこで関数が呼ばれているのか調べたり、処理時間を調べたり、メモリ使用量を調べたりするような関数です。 どんな関数や設定があるのかは、ここでは記載しません。 大量にありますので、英語ですが公式のドキュメントを見てもらった方が良いと思います。

• Xdebug: Documentation » Development Helpers

関数トレースの開始タイミングは、デフォルトではトリガーに設定されているので、条件を満たしてあげる必要があります。 GETパラメーターからトリガーする場合は、URLのGETパラメーターに XDEBUG_TRIGGER を付けて、Webブラウザからアクセスするだけです。 GETパラメーターが1つ以上ある場合は、? ではなく & で繋げます。 ブラウザに Xdebug の拡張機能を入れている場合は、そちらを使って Cookie からトリガーした方が便利です。

https://example.com/hoge/hoge?XDEBUG_TRIGGER

トレースファイルの出力先のディレクトリは xdebug.output_dir で指定できます。 デフォルトの場合は一時ディレクトリ（"C:\Windows\Temp"）になります。

出力ファイル名の形式は xdebug.trace_output_name で指定できます。 デフォルトの場合は trace.%c 形式になります。%c はCRC32のことです。 タイムスタンプ形式にするには %t を使用します。

ファイルの拡張子は必ず .xt になり、変更できません。

[xdebug]
xdebug.mode=trace
xdebug.output_dir=C:\xampp\xdebug_output
xdebug.trace_output_name=trace.%t

cachegrind.out ファイルの出力先のディレクトリは xdebug.output_dir で指定できます。 デフォルトの場合は一時ディレクトリ（"C:\Windows\Temp"）になります。

出力ファイル名の形式は xdebug.profiler_output_name で指定できます。 デフォルトの場合は cachegrind.out.%p 形式になります。%p はプロセスIDのことです。 タイムスタンプ形式にするには %t を使用します。

[xdebug]
xdebug.mode=profile
xdebug.output_dir=C:\xampp\xdebug_output
xdebug.profiler_output_name=cachegrind.out.%t

ガベージコレクション統計を開始するには、2つの方法があります。

php -dxdebug.mode=gcstats -dxdebug.start_with_request=yes your_script.php

[xdebug]
xdebug.mode=gcstats

<?php
xdebug_start_gcstats();

// 調べたい処理

xdebug_stop_gcstats();

統計ファイルの出力先のディレクトリは xdebug.output_dir で指定できます。 デフォルトの場合は一時ディレクトリ（"C:\Windows\Temp"）になります。

出力ファイル名の形式は xdebug.gc_stats_output_name で指定できます。 デフォルトの場合は gcstats.%p 形式になります。%p はプロセスIDのことです。 タイムスタンプ形式にするには %t を使用します。

[xdebug]
xdebug.mode=gcstats
xdebug.output_dir=C:\xampp\xdebug_output
xdebug.gc_stats_output_name=gcstats.%t