XdebugでWordPressのPHPをデバッグする方法｜Xdebug 3の設定とVS Code連携

Xdebug は、PHP の拡張モジュールです。ブレークポイントで処理を止めて変数の中身を1行ずつ確かめる「ステップデバッグ」、エラー時に詳しい呼び出し履歴を出す機能、処理時間を調べるプロファイリングなどができます。WordPress のテーマやプラグインで「どこで値がおかしくなるのか分からない」ときに、var_dump() やログを入れて何度も試すより早く原因にたどり着けます。

この記事では、開発環境に Xdebug 3 を入れ、VS Code と連携して WordPress の PHP を調べる手順を説明します（2026年10月時点の Xdebug の公式ドキュメントに基づきます）。Xdebug は処理を大きく遅くするため、本番サーバーには入れず、ローカルやステージングの環境で使います。

Xdebug でできること

xdebug.mode という設定で、使う機能を選びます。カンマ区切りで複数を指定できます。

Xdebug をインストールする

Ubuntu / Debian

sudo apt-get install php-xdebug

# PPA などで特定の版の PHP を入れている場合は、その版のパッケージを入れる（例: PHP 8.3）
sudo apt-get install php8.3-xdebug

RHEL / Fedora 系

sudo dnf install php-xdebug

パッケージが無い場合

PECL でソースからビルドします。GCC と PHP の開発用ヘッダーが必要です。Xdebug の公式ドキュメントでは、PECL の後継の PIE（pie install xdebug/xdebug）も案内されています。

pecl install xdebug

PECL が php.ini に extension=xdebug.so を追加するよう促しても、従わないでください。Xdebug は zend_extension で読み込む拡張です。php.ini、または conf.d の中に作った 99-xdebug.ini などのファイルに、次の1行を書きます。

zend_extension=xdebug

Docker の公式 WordPress イメージ

公式の wordpress イメージ（Debian ベース）を使っている場合は、Dockerfile で次のように入れられます。

FROM wordpress:6-php8.3-apache
RUN pecl install xdebug && docker-php-ext-enable xdebug

読み込まれたか確認する

php -v

出力に with Xdebug v3.… の行があれば、CLI では読み込まれています。Web サーバー側で読み込まれているかは、管理画面の「ツール」→「サイトヘルス」→「情報」や、一時的に置いた phpinfo() のページで確認します。インストール後は、Apache または PHP-FPM を再起動してください。

Xdebug 3 の設定を書く

Xdebug の設定ファイル（Ubuntu なら /etc/php/8.3/mods-available/xdebug.ini のように、名前に xdebug を含むファイル）に、次の設定を追加します。zend_extension の行がすでにある場合は、その行は重ねて書きません。

xdebug.mode = develop,debug
xdebug.start_with_request = trigger
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.log = /tmp/xdebug.log

設定を変えたら、Apache または PHP-FPM を再起動します。

Xdebug 2 の設定名は使えない

Xdebug 3 では設定名が大きく変わりました。古い解説にある次の設定は、そのままでは効きません。

VS Code と連携する

VS Code の拡張機能「PHP Debug」をインストールし、WordPress のフォルダーを開いて、.vscode/launch.json を次のように作ります。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003
    }
  ]
}

Docker やリモートサーバーのように、PHP が見ているファイルの場所（例: /var/www/html）と、VS Code で開いているフォルダーが違う場合は、pathMappings で対応を指定します。指定しないと、ブレークポイントで止まりません。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

PhpStorm も、Xdebug 3 の既定のポート 9003 で待ち受けられます。設定方法は PhpStorm の公式ドキュメントを参照してください。

デバッグを始める

1. VS Code の「実行とデバッグ」で「Listen for Xdebug」を開始します。
2. 調べたいテーマやプラグインのファイル（例: functions.php）の行番号の左をクリックし、ブレークポイントを置きます。
3. トリガーを付けてページを開きます。xdebug.start_with_request = trigger の場合、URL に XDEBUG_TRIGGER を付けると、そのリクエストでデバッグが始まります。

https://example.test/sample-page/?XDEBUG_TRIGGER=1

XDEBUG_TRIGGER は、GET や POST のパラメーター、Cookie、環境変数のどれで渡してもかまいません。古い名前の XDEBUG_SESSION も使えます。管理画面の Ajax（admin-ajax.php）や REST API の呼び出しまで続けて止めたい場合は、ブラウザの拡張機能などで Cookie を付ける方法が便利です。

処理がブレークポイントで止まると、VS Code に変数の中身や呼び出し履歴が表示され、1行ずつ進めながら確認できます。

WP-CLI や PHP スクリプトをデバッグする

コマンドラインでは、環境変数を付けて実行します。

XDEBUG_SESSION=1 wp eval 'var_dump( get_option( "blogname" ) );'

Docker やリモートサーバーで動かす場合

xdebug.client_host は、PHP から見た「IDE が動いているパソコン」のアドレスです。PHP がコンテナや別のサーバーで動いていると、localhost では IDE に届きません。

• Docker Desktop: xdebug.client_host = host.docker.internal とします。Linux の Docker Engine では、docker run に --add-host=host.docker.internal:host-gateway を付けると同じ名前が使えます。
• リモートの開発サーバー: ポートを外部に開ける代わりに、SSH のリモートフォワードを使うと安全です。サーバー側の xdebug.client_host は localhost のままにし、パソコンから次のように接続しておきます。

# サーバーの 9003 番への接続を、手元のパソコンの 9003 番へ転送する
ssh -R 9003:localhost:9003 user@dev.example.com

つながらないときは、xdebug.log に書いたファイルを見ると、どのアドレスとポートに接続しようとして失敗したかが分かります。PHP のコードの中で xdebug_info() を呼ぶと、今の設定と有効な機能を一覧で確認できます。

WordPress のデバッグ設定と組み合わせる

Xdebug の develop モードでは、PHP のエラーや警告が出たときに、どの関数から呼ばれたかの履歴が付きます。WordPress 側でエラーを表示または記録する設定にしておくと、原因を追いやすくなります。開発環境の wp-config.php で次のように設定します。

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );     // wp-content/debug.log に記録する
define( 'WP_DEBUG_DISPLAY', true ); // 画面にも表示する（開発環境のみ）

プロファイリングで遅い処理を探す

ページの表示が遅い原因を探すときは、profile モードを使います。

xdebug.mode = profile
xdebug.start_with_request = trigger
xdebug.output_dir = /tmp

トリガーを付けてページを開くと、xdebug.output_dir に cachegrind.out. で始まるファイルができます。KCachegrind や QCacheGrind、PhpStorm のプロファイラー表示で開くと、どの関数に時間がかかっているかが分かります。プロファイルのファイルは大きくなりやすいため、調べ終わったら削除し、xdebug.mode を元に戻します。

使うときの注意

• 本番サーバーでは使わない: 有効にした機能によっては PHP の処理が大きく遅くなり、エラー時に内部の情報が画面に出ることもあります。本番では拡張モジュールそのものを読み込まないようにします。
• デバッグ用のポートを外部に開けない: 9003 番は IDE 側が待ち受けるポートです。インターネットに開けず、リモートでは SSH のフォワードを使います。
• 使わないときは止める: xdebug.mode = off にするか、Ubuntu なら sudo phpdismod xdebug で無効にし、Apache または PHP-FPM を再起動します。
• タイムアウトに注意: ブレークポイントで長く止めていると、PHP の max_execution_time や Web サーバーのタイムアウトで処理が打ち切られることがあります。

まとめ

• Xdebug は開発環境だけで使い、本番サーバーには入れない
• Xdebug 3 では xdebug.mode・xdebug.start_with_request・xdebug.client_host・xdebug.client_port（既定 9003）で設定する。Xdebug 2 の remote_* は使えない
• VS Code は「PHP Debug」拡張と launch.json、場所が違う環境では pathMappings を設定する
• XDEBUG_TRIGGER を付けたリクエストだけデバッグし、つながらないときは xdebug.log と xdebug_info() で確認する
• Docker では host.docker.internal、リモートサーバーでは SSH のリモートフォワードで IDE に接続する

関連記事:

• WordPressのデバッグモードを有効にする方法
• Query MonitorでWordPressをデバッグする
• 本番環境でWP_DEBUGを無効にする