VS CodeでPHPをデバッグする方法

VS CodeでPHPを効率よくデバッグする場合は、一般的に「PHP」「Xdebug」「PHP Debug拡張機能」を組み合わせます。

単純なPHPプログラムであれば、echoやvar_dump()を使って変数の中身を確認することもできます。

しかし、処理が複雑になると、どのタイミングで値がおかしくなったのかを追跡するのが難しくなります。

Xdebugを使えば、ブレークポイントで処理を停止したり、変数の値を確認したり、1行ずつ処理を進めたりできるため、PHPの不具合を効率よく調査できます。

ここでは、VS CodeでPHPをデバッグする基本的な設定方法から、ブレークポイントの使い方、デバッグできない場合の確認ポイントまで詳しく解説します。

VS CodeでPHPをデバッグするために必要なもの

VS CodeでPHPをステップデバッグする場合は、主に次の環境を用意します。

• PHP
• Xdebug
• VS Code
• PHP Debug拡張機能

PHPはプログラム本体を実行します。

Xdebugは、実行中のPHPとデバッガーを接続するためのPHP拡張機能です。

PHP Debugは、Xdebugから送られてくるデバッグ情報をVS Codeで扱えるようにする拡張機能です。

つまり、基本的な構成は次のようになります。

PHP
↓
Xdebug
↓
PHP Debug
↓
VS Code

VS Codeだけでは通常、PHPをブレークポイントで停止させたり、ステップ実行したりすることはできません。

PHPの本格的なデバッグを行う場合は、Xdebugなどのデバッガーを組み合わせます。

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

最初に、パソコン上でPHPを利用できるか確認します。

VS Codeでターミナルを開き、次のコマンドを実行してください。

php -v

PHPが正しくインストールされていれば、次のような情報が表示されます。

PHP 8.x.x (cli)

PHPのバージョンが表示されれば問題ありません。

一方、

php is not recognized

や、

command not found

などと表示される場合は、PHPがインストールされていないか、PHPの実行ファイルにPATHが設定されていない可能性があります。

VS CodeのPHP構文チェックで使用するPHPを指定する

PHPはインストールされているものの、VS Codeから認識されない場合は、settings.jsonでPHP実行ファイルを指定できます。

Windowsの場合は、例えば次のように設定します。

{
    "php.validate.executablePath": "C:/php/php.exe"
}

Linuxであれば、次のような設定になります。

{
    "php.validate.executablePath": "/usr/bin/php"
}

ただし、php.validate.executablePathは主にVS Code標準のPHP構文チェックで利用される設定です。

PHP Debug拡張機能が利用するPHP実行ファイルを指定したい場合は、環境に応じてphp.debug.executablePathを利用します。

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

PHPが利用できることを確認したら、次にXdebugがインストールされているか調べます。

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

php -v

Xdebugが読み込まれている環境では、出力の中に、

with Xdebug v3.x.x

などと表示される場合があります。

さらに確実に確認したい場合は、次のコマンドを使用します。

php -m

表示されたPHP拡張機能の一覧に、

xdebug

が含まれていれば、Xdebugが読み込まれています。

より詳しい設定内容を確認したい場合は、

php --ri xdebug

を実行します。

Xdebugのバージョンや現在の設定値を確認できます。

使用されているphp.iniを確認する

PHPでは、設定ファイルであるphp.iniを編集してXdebugを有効にします。

ただし、複数のPHP環境がインストールされている場合は、どのphp.iniが使用されているのか分かりにくいことがあります。

CLI版PHPで使用されているphp.iniは、次のコマンドで確認できます。

php --ini

例えば、

Loaded Configuration File: C:\php\php.ini

と表示された場合は、そのphp.iniがCLI版PHPで読み込まれています。

ブラウザ経由のPHPでは別のphp.iniを使う場合がある

ApacheやNginx、XAMPPなどを利用している場合、CLI版PHPとWebサーバー経由のPHPで異なるphp.iniが読み込まれることがあります。

その場合は、確認用のPHPファイルを作成します。

<?php
phpinfo();

ブラウザからこのPHPファイルへアクセスし、

Loaded Configuration File

の項目を確認します。

そこに表示されているファイルが、Webサーバー経由のPHPで使用されているphp.iniです。

なお、phpinfo()ではPHPやサーバーに関する多くの情報が表示されます。

確認用に作成したファイルは、確認後に削除しておくと安全です。

Xdebugをインストールする

Xdebugがインストールされていない場合は、PHP環境に追加します。

具体的な方法はOSやPHPの導入方法によって異なります。

WindowsでXdebugをインストールする

Windowsでは、使用しているPHPに対応したXdebugのDLLを用意します。

PHPの環境によって、

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

などが異なるため、対応するXdebugを選ぶ必要があります。

XdebugのDLLをPHPのextフォルダなどに配置し、php.iniへ設定を追加します。

例えば、

zend_extension="C:\php\ext\php_xdebug.dll"

とします。

環境によっては、

zend_extension=xdebug

のような記述でも読み込めますが、初心者の場合はXdebugの実際のファイルパスを指定したほうが分かりやすいでしょう。

LinuxでXdebugをインストールする

Linuxでは、ディストリビューションによってパッケージ管理システムからXdebugをインストールできる場合があります。

Ubuntu系では、例えば次のようなコマンドを使用します。

sudo apt install php-xdebug

ただし、PHPのバージョンや使用しているリポジトリによってパッケージ名が異なる場合があります。

macOSでXdebugをインストールする

macOSでは、PHPの導入方法によってはPECLを利用できます。

例えば、

pecl install xdebug

などです。

HomebrewでPHPをインストールしている場合など、環境によって設定方法が異なるため、導入後にXdebugが正しく読み込まれているか確認しましょう。

Xdebugを設定する

Xdebugをインストールしたら、php.iniなどにデバッグ設定を追加します。

現在一般的に利用されているXdebug 3では、例えば次のように設定できます。

[xdebug]
zend_extension="Xdebugの実際のファイルパス"
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

xdebug.modeをdebugにする

PHPのステップデバッグを利用する場合は、

xdebug.mode=debug

を設定します。

Xdebugには複数のモードがありますが、ブレークポイントやステップ実行を利用するにはdebugモードが必要です。

Xdebug 3ではポート9003を使用する

Xdebug 3では、デバッグ接続に使用される標準ポートが、

9003

です。

そのため、

xdebug.client_port=9003

と設定します。

古いXdebug 2では9000番ポートが利用されていたため、古い記事や設定例では、

9000

が記載されている場合があります。

Xdebug 3を利用する場合は、基本的に9003を使用します。

xdebug.start_with_requestを設定する

分かりやすい設定として、

xdebug.start_with_request=yes

があります。

この設定では、PHPが実行されるたびにXdebugがデバッガーへ接続しようとします。

初心者がデバッグ環境を構築するときには比較的分かりやすい設定です。

一方で、毎回デバッグ接続する必要がない場合は、

xdebug.start_with_request=trigger

を利用する方法もあります。

triggerを指定すると、XDEBUG_TRIGGERなどのトリガーが存在するときだけデバッグを開始できます。

大規模な開発環境や、必要なリクエストだけデバッグしたい場合に便利です。

PHPやWebサーバーを再起動する

php.iniを変更しただけでは、設定が反映されない場合があります。

Apache、PHP-FPM、XAMPPなどを利用している場合は、設定変更後にサービスを再起動しましょう。

例えばXAMPPであれば、Apacheを一度停止してから再度起動します。

その後、

php --ri xdebug

やphpinfo()を利用して、変更したXdebug設定が反映されているか確認します。

VS CodeにPHP Debugをインストールする

次に、VS Code側へPHP Debug拡張機能をインストールします。

VS Codeの左側にある「拡張機能」を開き、

PHP Debug

と検索します。

「PHP Debug」という拡張機能をインストールします。

この拡張機能が、XdebugとVS Codeの間を仲介する役割を持ちます。

launch.jsonを作成する

Webアプリケーションをデバッグする場合は、.vscode/launch.jsonを作成してデバッグ設定を保存しておくと便利です。

VS Codeの「実行とデバッグ」を開き、「launch.jsonファイルを作成します」などを選択します。

PHPを選ぶと、.vscode/launch.jsonを作成できます。

基本的な設定は次のとおりです。

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

Xdebug側が9003番ポートを使用している場合は、VS Code側も、

"port": 9003

に合わせます。

なお、利用方法によってはlaunch.jsonを作成せずにPHPファイルをデバッグできる場合もあります。

ただし、WebアプリケーションやLaravelなどのプロジェクトを扱う場合は、launch.jsonを作成して設定を管理したほうが分かりやすいでしょう。

参考サイト

Check! Visual Studio Code で PHP をデバッグ実行 (Xdebug) #VSCode – Qiita

PHPコードにブレークポイントを設定する

デバッグ環境を設定したら、PHPコードにブレークポイントを設定します。

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

<?php

$name = 'Taro';
$age = 25;

$message = $name . ' is ' . $age . ' years old.';

echo $message;

停止させたい行の左側をクリックすると、赤い丸が表示されます。

例えば、

$message = $name . ' is ' . $age . ' years old.';

の行にブレークポイントを設定すると、PHPがその位置まで実行されたときに処理を停止できます。

VS CodeでXdebugの接続待ちを開始する

ブレークポイントを設定したら、VS Codeの「実行とデバッグ」を開きます。

先ほど作成した、

Listen for Xdebug

を選択し、F5キーなどでデバッグを開始します。

VS CodeがXdebugからの接続を待機する状態になります。

ブラウザからPHPへアクセスする

Webアプリケーションの場合は、VS Codeを待機状態にしてからブラウザで対象のページへアクセスします。

例えば、

http://localhost/test.php

です。

処理の流れは次のようになります。

ブラウザ
↓
Webサーバー
↓
PHP
↓
Xdebug
↓
VS Code

XdebugとVS Codeの接続に成功すると、設定したブレークポイントでPHPの実行が停止します。

変数の値を確認する

ブレークポイントで処理が停止すると、VS Codeのデバッグ画面から変数の値を確認できます。

例えば、

$name = 'Taro';
$age = 25;

という変数があれば、デバッグ画面に、

$name = "Taro"
$age = 25

などと表示されます。

これにより、

「この時点で変数にはどの値が入っているのか」

を確認できます。

var_dump()をコードに追加しなくても値を追跡できるため、不具合の原因を調査しやすくなります。

ステップ実行を利用する

VS Codeでデバッグ中は、処理を1行ずつ進めることができます。

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

Continue
Step Over
Step Into
Step Out
Restart
Stop

Step Over

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

例えば、

$result = calculate($price);

というコードがある場合、calculate()の内部には入らず、関数の処理が終了したあとの次の行へ進みます。

関数の内部を詳しく調べる必要がない場合に便利です。

Step Into

Step Intoは、呼び出している関数の内部へ移動する操作です。

例えば、

$result = calculate($price);

という処理でStep Intoを実行すると、calculate()関数の中へ移動できます。

関数内のどの処理で値がおかしくなっているのか調べたいときに利用します。

Step Out

Step Outを使うと、現在の関数の残りを実行して、呼び出し元へ戻ることができます。

関数内部へ入ったものの、それ以上詳しく調べる必要がない場合に便利です。

WATCHで値を監視する

VS CodeにはWATCH機能があります。

WATCHへ変数や式を登録しておくと、デバッグ中に値の変化を確認できます。

例えば、

$price * $quantity

をWATCHへ登録すると、ステップ実行するたびに計算結果を確認できます。

また、

count($items)

などの式を登録することも可能です。

ただし、デバッグ中に評価する式によってプログラムの状態が変化する可能性もあります。

副作用を持つ関数などを不用意に実行しないよう注意しましょう。

CALL STACKで処理の流れを確認する

複数の関数やクラスを経由しているプログラムでは、CALL STACKも重要です。

例えば、

index.php
↓
Controller
↓
Service
↓
Repository

のような処理になっている場合、CALL STACKを見ることで、どの関数から現在の処理が呼び出されたのかを確認できます。

LaravelやSymfonyなど、処理の呼び出し階層が深くなりやすいPHPフレームワークをデバッグするときにも便利です。

CLIのPHPファイルをデバッグする方法

PHPはWebブラウザ経由だけでなく、CLIから実行するスクリプトもデバッグできます。

例えば、

php test.php

のように実行するPHPファイルです。

PHP Debugでは、現在開いているPHPファイルを直接実行する設定も利用できます。

例えば、

{
    "name": "Launch currently open script",
    "type": "php",
    "request": "launch",
    "program": "${file}",
    "cwd": "${fileDirname}",
    "port": 0,
    "runtimeArgs": [
        "-dxdebug.start_with_request=yes"
    ]
}

といった設定です。

簡単なPHPプログラムやバッチ処理などを調査するときは、ブラウザ経由よりCLIデバッグのほうが手軽な場合があります。

PHPの組み込みWebサーバーでデバッグする方法

PHPには簡易的なWebサーバー機能があります。

例えば、PHPプロジェクトのディレクトリで、

php -S localhost:8000

を実行すると、

http://localhost:8000

からPHPへアクセスできます。

ApacheやNginxなどを用意せずに簡単なPHPプログラムを動かしたい場合に便利です。

この場合もXdebugとPHP Debugを組み合わせてデバッグできます。

ブレークポイントで止まらない場合の確認ポイント

PHPデバッグでは、

「ブレークポイントを設定したのに処理が停止しない」

というトラブルが比較的よく発生します。

その場合は、次の項目を順番に確認しましょう。

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

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

php --ri xdebug

Xdebugの情報が表示されない場合は、XdebugがPHPに読み込まれていません。

zend_extensionの設定やXdebugのインストール状態を確認しましょう。

xdebug.modeがdebugになっているか確認する

ステップデバッグには、

xdebug.mode=debug

が必要です。

例えば、

xdebug.mode=develop

だけになっている場合は、ステップデバッグを利用できません。

ポート番号が一致しているか確認する

Xdebug側が、

xdebug.client_port=9003

であれば、launch.json側も、

"port": 9003

にします。

双方のポート番号が異なっていると接続できません。

xdebug.start_with_requestを確認する

毎回デバッグ接続させたい場合は、

xdebug.start_with_request=yes

にします。

一方、

xdebug.start_with_request=trigger

の場合は、デバッグを開始するためのトリガーが必要です。

Webサーバーを再起動する

php.iniを変更したあとにApacheやPHP-FPMなどを再起動していない場合、設定が反映されていない可能性があります。

設定変更後はWebサーバーやPHPの実行環境を再起動しましょう。

CLIでは動くのにブラウザではデバッグできない場合

CLIではXdebugが動くにもかかわらず、ブラウザから実行したPHPではデバッグできないことがあります。

その原因として多いのが、

CLI版PHP

と、

Webサーバー版PHP

で異なるphp.iniを使用しているケースです。

CLI側では、

php --ini

を確認します。

Web側では、

<?php
phpinfo();

をブラウザから開きます。

それぞれの、

Loaded Configuration File

を比較してください。

異なるphp.iniが表示される場合は、Webサーバー側で使用されているphp.iniにもXdebugの設定が必要です。

DockerでPHPをデバッグする方法

Docker環境では、PHPがコンテナ内、VS CodeがホストPC上で動いていることがあります。

その場合は、XdebugからホストPCへ接続できるように設定する必要があります。

xdebug.client_hostを設定する

Docker Desktopなど、host.docker.internalを利用できる環境では、

xdebug.client_host=host.docker.internal
xdebug.client_port=9003

のように設定できます。

重要なのは、PHPコンテナからVS Codeが動いているホストPCへ到達できるアドレスを指定することです。

環境によってはhost.docker.internalをそのまま利用できない場合もあるため、Docker環境に合わせて設定します。

pathMappingsを設定する

Dockerでは、コンテナ内とホストPC上でPHPファイルのパスが異なることがあります。

例えば、コンテナ側が、

/var/www/html

で、ホスト側がVS Codeのワークスペースになっている場合です。

その場合は、launch.jsonにpathMappingsを設定します。

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

pathMappingsが正しく設定されていないと、ブレークポイントが灰色になったり、正しい行で停止しなかったりすることがあります。

Xdebugのログを確認する

XdebugとVS Codeがどうしても接続できない場合は、Xdebugのログを有効にすると原因を調査しやすくなります。

例えば、php.iniへ次のように設定します。

xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

Xdebugがどのアドレスやポートへ接続しようとしているかなどを確認できます。

また、PHP Debug側でもlaunch.jsonへ、

"log": true

を追加すると、接続状況の調査に役立つ場合があります。

VS CodeでPHPをデバッグするときの基本設定

初めてPHPのデバッグ環境を作る場合は、まずシンプルな構成から試すと分かりやすいでしょう。

php.iniは、例えば次のようにします。

[xdebug]
zend_extension="Xdebugの実際のファイルパス"
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

同じPC上でPHPとVS Codeを動かしている場合は、必要に応じて、

xdebug.client_host=127.0.0.1

を指定できます。

VS Code側の.vscode/launch.jsonは、次のようにします。

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

VS CodeでPHPをデバッグする基本的な流れ

実際にデバッグするときは、次のような流れになります。

1. PHPをインストールする
2. Xdebugをインストールする
3. php.iniでXdebugを有効にする
4. xdebug.mode=debugを設定する
5. VS CodeへPHP Debugをインストールする
6. launch.jsonを作成する
7. PHPコードへブレークポイントを設定する
8. VS CodeでListen for Xdebugを開始する
9. PHPをブラウザやCLIから実行する
10. ブレークポイントで処理を停止する
11. 変数やCALL STACKを確認する
12. Step OverやStep Intoで処理を追跡する

まとめ

VS CodeでPHPをデバッグする場合は、PHPにXdebugを導入し、VS CodeへPHP Debug拡張機能をインストールする方法が一般的です。

特にXdebug 3を利用する場合は、

xdebug.mode=debug

を有効にし、デバッグポートには通常、

9003

を使用します。

また、VS Code側のlaunch.jsonでも同じ9003番ポートを設定することが重要です。

ブレークポイントを利用すれば、PHPの実行を途中で停止し、変数の値や処理の流れを確認できます。

さらに、Step OverやStep Into、WATCH、CALL STACKなどを利用すれば、echoやvar_dump()だけに頼るよりも効率的に不具合の原因を探せます。

デバッグできない場合は、Xdebugが正しく読み込まれているか、xdebug.modeがdebugになっているか、9003番ポートが一致しているか、正しいphp.iniを編集しているかを順番に確認すると原因を特定しやすくなります。

以上、VS CodeでPHPをデバッグする方法についてでした。

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