MENU
contact

PHPのXdebugとは何か、特徴や設定方法について

PHP

採用はこちら

Xdebugとは、PHPの開発やデバッグを支援するためのPHP拡張機能です。
PHP本体に標準搭載されている機能ではなく、必要に応じて追加して利用します。

PHPの不具合を調べる場合、var_dump()やecho、ログ出力などを使って変数の値を確認する方法があります。
しかし、プログラムが複雑になると、どのタイミングで値が変化したのか、どの関数を経由して処理されたのかを追いかけるのが難しくなります。

Xdebugを導入すると、プログラムを任意の位置で一時停止したり、変数の値を確認したり、1行ずつコードを実行したりできます。
さらに、エラー情報の強化、関数呼び出しのトレース、プロファイリング、コードカバレッジなども利用できます。

特にVisual Studio CodeやPhpStormなどのIDE・エディタと組み合わせることで、PHPのデバッグ作業を大幅に効率化できます。

目次

Xdebugの主な特徴

ステップデバッグができる

Xdebugの代表的な機能がステップデバッグです。

ステップデバッグでは、PHPプログラムを実行しながら、任意の場所で処理を停止できます。
停止した時点で変数の値やオブジェクトの状態を確認しながら、1行ずつコードを進められます。

たとえば、次のコードがあるとします。

<?php

$price = 1000;
$quantity = 3;

$total = $price * $quantity;

echo $total;

通常はPHPを実行すると、最後まで一気に処理されます。

Xdebugを使えば、次の行にブレークポイントを設定できます。

$total = $price * $quantity;

処理を停止した時点で、次のような変数の状態を確認できます。

$price = 1000
$quantity = 3

計算前後の値を確認できるため、計算結果がおかしい場合などに原因を特定しやすくなります。

ブレークポイントを設定できる

ブレークポイントとは、プログラムの処理を一時停止させる位置のことです。

たとえば、次のようなループ処理があるとします。

foreach ($users as $user) {
    $name = $user['name'];

    echo $name;
}

$name = $user['name'];の行にブレークポイントを設定すると、ループが実行されるたびに$userの内容を確認できます。

特定の条件でのみ停止する条件付きブレークポイントを利用できるIDEもあります。
大量のデータを処理している場合でも、問題が発生する条件だけを効率的に調査できます。

変数の値を確認できる

ステップデバッグ中は、現在の変数や配列、オブジェクトなどの状態を確認できます。

たとえば、次の配列があるとします。

$user = [
    'id' => 10,
    'name' => 'Taro',
    'email' => 'taro@example.com'
];

デバッグ中にIDEの変数表示機能を利用すると、id、name、emailなどの値を確認できます。

LaravelやSymfonyなどのフレームワークでは、多数のオブジェクトや配列が利用されます。
そのため、Xdebugを使って内部状態を確認できることは大きなメリットです。

1行ずつコードを実行できる

XdebugをIDEと連携すると、プログラムを1行ずつ進められます。

代表的な操作には次のようなものがあります。

  • Step Over
  • Step Into
  • Step Out
  • Continue

Step Overは、現在の行を実行して次の行へ進む操作です。

Step Intoは、呼び出されている関数やメソッドの内部に入ります。

Step Outは、現在の関数やメソッドから抜けて呼び出し元へ戻ります。

Continueは、次のブレークポイントまで処理を続行します。

これらを利用することで、PHPの処理がどの順番で進んでいるのかを細かく確認できます。

Xdebugの代表的な機能

Development Helpers

Xdebugには、PHP開発を支援するDevelopment Helpersがあります。

代表的な機能の一つが、var_dump()の表示を見やすくする機能です。

通常のPHPでも次のように変数を確認できます。

var_dump($user);

Xdebugの開発支援機能を利用すると、変数や配列などの情報をより確認しやすくできます。

また、PHPでNotice、Warning、Exceptionなどが発生した場合に、スタックトレースを確認しやすくなる点も特徴です。

Function Trace

Function Traceは、PHPの実行中にどの関数やメソッドが呼び出されたのかを記録する機能です。

たとえば、Webアプリケーションで次のような処理が行われているとします。

index.php
↓
UserController
↓
UserService
↓
UserRepository
↓
データベース処理

Function Traceを利用すると、関数やメソッドの呼び出し順序を追跡できます。

設定によって、引数や戻り値などの情報も記録できます。

処理の流れが複雑なアプリケーションで、どのコードを経由しているのかを確認したい場合に便利です。

Profiling

Profilingは、PHPプログラムのパフォーマンスを分析するための機能です。

Webサイトの表示が遅い場合でも、単純にソースコードを眺めるだけでは、どの関数に時間がかかっているのか分からないことがあります。

Xdebugのプロファイリング機能を利用すると、関数の実行時間や呼び出し状況などを記録できます。

取得したプロファイルデータを対応する分析ツールで確認することで、処理時間の大きい関数などを特定できます。

ただし、Xdebugが自動的に「データベース処理が何秒」と分類して表示するわけではありません。
プロファイルデータを基に、ボトルネックとなっている処理を分析します。

Code Coverage

Code Coverageは、テストによってPHPコードのどの部分が実行されたのかを確認するための機能です。

PHPUnitなどのテストツールと組み合わせて利用されることがあります。

たとえば、テストを実行した結果として、どの行が実行され、どの行が実行されていないのかを調べられます。

コードカバレッジには、単純な行単位のカバレッジだけでなく、分岐や実行経路に関する情報もあります。

テストコードがどこまで対象コードを網羅しているのかを確認する際に役立ちます。

Xdebugをインストールする方法

Linuxでインストールする場合

UbuntuやDebian系のLinuxでは、パッケージマネージャーからXdebugをインストールできる場合があります。

代表的な例は次のとおりです。

sudo apt install php-xdebug

インストール後は、PHPからXdebugが読み込まれているか確認します。

ただし、Linuxディストリビューションのリポジトリに含まれているXdebugが、必ずしも最新バージョンとは限りません。

利用するPHPのバージョンや開発環境に応じて、別のインストール方法を選択する場合もあります。

PIEを利用してインストールする場合

現在のPHP拡張機能では、PIEを利用してインストールする方法もあります。

Xdebugの場合、基本的には次のようなコマンドでインストールできます。

pie install xdebug/xdebug

PIEはPHP拡張機能をインストールするための仕組みです。

Xdebugのインストール方法としては、PIEだけでなく、PECLやOSのパッケージマネージャーなど複数の方法があります。

利用環境に適した方法を選択することが重要です。

Windowsでインストールする場合

Windowsでは、利用しているPHP環境に対応するXdebugをインストールする必要があります。

特に次の項目を確認します。

  • PHPのバージョン
  • 32bitまたは64bit
  • Thread SafeまたはNon Thread Safe
  • PHPのビルド条件

PHP環境とXdebugのDLLが一致していないと、正しく読み込めない場合があります。

どのXdebugを利用すればよいか分からない場合は、Xdebug公式のInstallation Wizardを利用すると確認しやすくなります。

Xdebugがインストールされているか確認する方法

php -mで確認する

XdebugがPHPに読み込まれているか確認する簡単な方法が、次のコマンドです。

php -m

一覧の中に次の表示があれば、Xdebugが読み込まれています。

xdebug

php –ri xdebugで確認する

Xdebugに関する詳しい情報を確認する場合は、次のコマンドも便利です。

php --ri xdebug

Xdebugが正常に読み込まれていれば、バージョンや各種設定情報などを確認できます。

php -vで確認する

次のコマンドでも、環境によってXdebugの読み込み状況を確認できます。

php -v

ただし、Xdebugが有効かどうかを確認する目的では、php -mやphp --ri xdebugのほうが分かりやすい場合があります。

xdebug_info()で確認する

WebブラウザからXdebugの設定を確認したい場合は、次のPHPコードを利用できます。

<?php

xdebug_info();

Xdebugのバージョンや設定、デバッグ接続に関する診断情報などを確認できます。

読み込まれているphp.iniを確認する方法

Xdebugを設定したにもかかわらず反映されない場合は、PHPがどの設定ファイルを読み込んでいるのか確認します。

CLIでは次のコマンドを利用できます。

php --ini

PHPが読み込んでいるphp.iniや追加設定ファイルの場所が表示されます。

ただし、php --iniで確認できるのは、基本的にそのコマンドを実行したPHP CLI環境の設定です。

Webサーバーでは、Apache、PHP-FPM、CLIなどで異なる設定ファイルを利用している場合があります。

Webサーバー側の設定を調べる場合は、必要に応じてphpinfo()などで確認します。

Xdebug 3の基本的な設定方法

Xdebug 3ではxdebug.modeを使用する

Xdebug 3では、主にxdebug.modeを利用して必要な機能を有効にします。

ステップデバッグを利用する場合は、次のように設定します。

xdebug.mode=debug

開発支援機能も利用する場合は、次のように複数指定できます。

xdebug.mode=develop,debug

主なモードには次のようなものがあります。

develop
debug
coverage
gcstats
profile
trace

すべての機能を常に有効にするのではなく、用途に必要な機能だけを有効にするのが基本です。

xdebug.start_with_requestを設定する

xdebug.start_with_requestは、Xdebugの機能をいつ開始するか設定する項目です。

たとえば次のように設定すると、リクエスト開始時から該当するXdebug機能を開始します。

xdebug.start_with_request=yes

一方、必要なときだけデバッグを開始したい場合は、次の設定を利用できます。

xdebug.start_with_request=trigger

triggerを利用すると、トリガーが指定されたときだけデバッグを開始できます。

ローカル開発環境では、毎回IDEへ接続を試みる必要がないため、triggerが便利な場合があります。

XDEBUG_TRIGGERを利用する

Xdebug 3では、必要なときにデバッグを開始するためのトリガーとしてXDEBUG_TRIGGERを利用できます。

環境変数などを使ってトリガーを指定することが可能です。

古いXdebugの記事では、XDEBUG_SESSIONなど別の設定を見かける場合があります。

現在のXdebug 3について調べる場合は、Xdebug 3向けの情報かどうかを確認することが重要です。

xdebug.client_hostを設定する

xdebug.client_hostには、Xdebugが接続するデバッグクライアントのホストを指定します。

たとえばPHPとIDEが同じPC上で動作している場合は、次のような設定になることがあります。

xdebug.client_host=localhost

重要なのは、XdebugはPHP側でデバッグ接続を待つのではなく、基本的にXdebug側からIDEへ接続するという点です。

xdebug.client_portを設定する

Xdebug 3のステップデバッグでは、デフォルトで9003番ポートが利用されます。

xdebug.client_port=9003

IDE側も同じポートでXdebugからの接続を受け付ける必要があります。

古いXdebug 2では9000番ポートが標準だったため、古い記事を参考にすると接続できない場合があります。

Xdebugの基本設定例

ローカル環境でステップデバッグを行う場合、設定例は次のようになります。

zend_extension=xdebug

xdebug.mode=develop,debug
xdebug.start_with_request=trigger

xdebug.client_host=localhost
xdebug.client_port=9003

これはあくまで一般的なローカル開発環境向けの一例です。

Dockerや仮想環境を利用している場合は、特にxdebug.client_hostの設定を環境に合わせて変更する必要があります。

VS CodeとXdebugを連携する方法

PHPデバッグ用の拡張機能を導入する

VS CodeでXdebugを利用する場合は、XdebugのDBGpプロトコルに対応したPHPデバッグ用拡張機能を導入します。

XdebugとIDEの関係は、おおまかに次のようになります。

ブラウザ
↓
Webサーバー
↓
PHP
↓
Xdebug
↓
IDE

Xdebug自身がGUIのデバッガー画面を提供するわけではありません。

XdebugがPHPのデバッグ情報をIDEへ送信し、IDE側で変数やブレークポイントなどを表示します。

IDEとXdebugのポートを合わせる

PHP側で次の設定を利用している場合を考えます。

xdebug.client_port=9003

この場合、VS CodeなどのIDE側でも9003番ポートで接続を待ち受けるように設定します。

ポート番号が一致していないと、XdebugからIDEへ接続できません。

DockerでXdebugを利用する場合の注意点

localhostはコンテナ自身を指す

DockerでXdebugを利用する場合、特に注意したいのがxdebug.client_hostです。

PHPがコンテナ内で動作している状態で次の設定を行うとします。

xdebug.client_host=localhost

この場合のlocalhostは、通常PHPコンテナ自身を指します。

ホストOS上でVS CodeやPhpStormが動作している場合、IDEに接続できない可能性があります。

host.docker.internalを利用できる場合がある

Docker Desktopなどの環境では、次のように設定できることがあります。

xdebug.client_host=host.docker.internal

ただし、host.docker.internalがすべてのOSやDocker環境で同じように利用できるとは限りません。

利用しているDocker環境のネットワーク構成を確認したうえで設定する必要があります。

xdebug.discover_client_hostを利用する場合

Xdebugには、HTTPリクエスト情報などから接続先を判定するxdebug.discover_client_hostという設定もあります。

ただし、HTTPヘッダーなどを接続先の判定に利用する構成では、セキュリティに注意する必要があります。

外部からアクセス可能な本番環境などで安易に有効化するのではなく、ローカル環境や信頼できるネットワークを中心に利用するのが安全です。

Xdebugが接続できない場合の確認ポイント

Xdebugが読み込まれているか確認する

まず、次のコマンドを実行します。

php -m

一覧にxdebugが表示されるか確認します。

さらに詳しく確認する場合は次のコマンドも利用できます。

php --ri xdebug

php.iniを確認する

設定内容に問題がなくても、編集しているphp.iniが実際には利用されていない場合があります。

CLIでは次のコマンドで確認できます。

php --ini

Webサーバー側とCLI側で設定ファイルが異なるケースもあるため注意が必要です。

xdebug.modeを確認する

ステップデバッグを利用する場合は、debugモードが必要です。

xdebug.mode=debug

たとえば次の設定だけでは、ステップデバッグは有効になりません。

xdebug.mode=develop

ステップデバッグと開発支援機能の両方を利用するなら、次のように設定できます。

xdebug.mode=develop,debug

IDEが待ち受け状態になっているか確認する

XdebugはIDEへ接続するため、IDE側でデバッグ接続を受け付ける状態になっている必要があります。

IDEが待ち受けていない場合、Xdebug側で接続エラーが発生します。

ポート番号を確認する

Xdebug 3の標準ポートは9003です。

xdebug.client_port=9003

IDE側でも同じポートが設定されているか確認します。

古い設定として次のような記述が残っている場合は注意が必要です。

xdebug.remote_port=9000

これはXdebug 2時代の設定です。

Xdebug 2とXdebug 3の違い

Xdebug 2ではremote系の設定が使われていた

古いXdebug 2では、次のような設定が利用されていました。

xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_host=localhost
xdebug.remote_port=9000

現在のXdebug 3では設定体系が変更されています。

Xdebug 3ではmodeやclient系の設定を使う

Xdebug 3では、次のような設定を利用します。

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=localhost
xdebug.client_port=9003

特に重要なのが、次の変更点です。

remote_enable
↓
xdebug.mode

remote_autostart
↓
xdebug.start_with_request

remote_host
↓
xdebug.client_host

remote_port
↓
xdebug.client_port

さらに、標準ポートも9000から9003へ変更されています。

Xdebugについて検索すると古いXdebug 2向けの記事も多く見つかるため、使用しているXdebugのバージョンを確認することが重要です。

Xdebugを本番環境で使う場合の注意点

基本的には開発環境で利用する

Xdebugは、基本的に開発やデバッグを支援するためのツールです。

そのため、一般的には次のように使い分けます。

開発環境：Xdebugを利用
本番環境：原則として無効化

Xdebugにはステップデバッグ、プロファイリング、トレース、コードカバレッジなどの機能があり、通常の本番運用では必要ないことが多いためです。

必要なモードだけを有効化する

Xdebug 3では、xdebug.modeを利用して必要な機能だけを有効化できます。

たとえばステップデバッグだけを利用する場合は次のようにします。

xdebug.mode=debug

不要な機能まで常時有効にしないことが重要です。

本番環境でXdebugをロードする特別な理由がない場合は、無効化しておくのが一般的です。

Xdebugを使うメリット

var_dump()を大量に追加しなくても調査できる

Xdebugを使わずにデバッグすると、次のようなコードを大量に追加することがあります。

var_dump($a);
var_dump($b);
var_dump($c);

Xdebugではブレークポイントを利用して、コードを書き換えずに変数を確認できます。

デバッグ後にvar_dump()を削除し忘れるといったミスも防ぎやすくなります。

複雑な処理を追跡しやすい

条件分岐やループ、クラス、フレームワークを利用したコードでは、処理が複雑になりやすくなります。

Xdebugを利用すれば、次のような流れで原因を調査できます。

ブレークポイントで停止
↓
変数を確認
↓
1行進める
↓
値の変化を確認
↓
関数の内部へ移動
↓
問題が発生する場所を特定

大規模なPHPアプリケーションほど、Xdebugの効果を実感しやすくなります。

Xdebugを使う際のデメリット

設定項目が多い

Xdebugを使うには、PHPだけでなくIDEやネットワークについても理解する必要があります。

特にDocker環境では、次の要素が関係します。

PHP
Xdebug
Docker
IDE
ネットワーク
ポート

接続できない場合は、それぞれを切り分けながら原因を調査する必要があります。

実行時のオーバーヘッドが発生する場合がある

Xdebugのデバッグ、トレース、プロファイリング、コードカバレッジなどを利用すると、通常のPHP実行に追加処理が発生します。

そのため、必要な機能だけを有効にし、基本的には開発環境で利用することが重要です。

古い情報に注意する必要がある

Xdebug 2とXdebug 3では設定方法が大きく異なります。

古い記事で次の設定を見かける場合があります。

xdebug.remote_enable
xdebug.remote_host
xdebug.remote_port

これらはXdebug 2向けの設定です。

現在のXdebug 3を利用する場合は、Xdebug 3対応の記事や公式ドキュメントを確認する必要があります。

Xdebugが向いているケース

PHPの不具合を詳しく調査したい場合

Xdebugは、次のような問題を調査する場合に向いています。

  • 条件分岐が期待どおりに動かない
  • 変数の値が途中で変化している
  • ループ内で特定のデータだけ問題が発生する
  • どの関数からエラーが発生したのか分からない
  • オブジェクトの内部状態を確認したい

LaravelやSymfonyをデバッグしたい場合

LaravelやSymfonyなどのPHPフレームワークでは、多数のクラスやメソッドが連携して処理されます。

Xdebugを使うことで、Controller、Service、Modelなどをまたいで処理の流れを追跡しやすくなります。

PHPUnitのテストを詳しく分析したい場合

PHPUnitなどのテストツールとXdebugを組み合わせれば、コードカバレッジ情報を取得できます。

どのコードがテストされていないのか確認する際にも役立ちます。

PHPのパフォーマンスを分析したい場合

Xdebugのプロファイリング機能を利用すると、どの関数に処理時間がかかっているのかを分析できます。

Webアプリケーションの速度低下の原因を調査する場合にも利用できます。

まとめ

Xdebugとは、PHPのデバッグや開発を支援するためのPHP拡張機能です。

代表的な機能には、ステップデバッグ、ブレークポイント、変数確認、Function Trace、Profiling、Code Coverageなどがあります。

特にVS CodeやPhpStormなどのIDEと組み合わせることで、PHPコードを途中で停止し、変数を確認しながら1行ずつ処理を追跡できます。

Xdebug 3でステップデバッグを利用する場合は、次のような設定が基本となります。

zend_extension=xdebug

xdebug.mode=develop,debug
xdebug.start_with_request=trigger

xdebug.client_host=localhost
xdebug.client_port=9003

ただし、Dockerを利用している場合はxdebug.client_hostを環境に合わせて変更する必要があります。

また、Xdebug 2ではxdebug.remote_*系の設定や9000番ポートが利用されていたため、古い記事を参考にすると設定が合わない場合があります。

Xdebugを導入すれば、var_dump()だけに頼ったデバッグから、ブレークポイントで処理を停止し、変数や処理の流れを確認しながら原因を追跡する本格的なデバッグへ移行できます。

PHPで複雑なWebアプリケーションを開発する場合や、不具合の原因を効率的に特定したい場合に非常に役立つツールです。

以上、PHPのXdebugとは何か、特徴や設定方法についてでした。

最後までお読みいただき、ありがとうございました。

PHP
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

  1. ホーム
  2. PHP
  3. PHPのXdebugとは何か、特徴や設定方法について
目次