【PHP】XAMPP環境でVisual Studio Codeのデバッグ機能が動かずに嵌った話と解決方法

最近、PHPのプログラムを弄るのにVisual Studio Code（以下VS Code）を使うようにしています。

「PHP Debug」拡張機能と、PHPのXDebugを組み合わせて、ローカルのXAMPP環境でステップ実行したいだけだったのですが、動くまでに少し時間が掛かりました。

色々なサイトで紹介されている記事を参考にして試しましたが、PHPやXDebugのバージョンを最新のものにしている事もあって、最初はなかなか上手くいきませんでした。

ここでは、わたしが動くようになった環境と設定を書いておきます。

実行環境

また、XAMPPはCドライブ直下にインストール（デフォルト設定のまま）してあるものとします。

VS Codeの「settings.json」

VS Codeを起動して、以下画像のように「ファイル」→「ユーザ設定」→「設定」と進みます。

「設定」画面が開きますので、上部の検索ボックス（①）の欄に「settings.json」と入力します。

すると、「settings.jsonで編集」という項目が出てくるのでクリックします。

settings.jsonの中には、VS Codeで自分がカスタマイズしたユーザ用の設定が保存されています。
（例えばスペースの表示設定やフォントサイズなど）

ここに、以下の設定を追記（もしくは既にある場合はphp.exeまでのパスを書き換え）します。

    "php.validate.executablePath": "C:\\xampp\\php\\php.exe",
    "php.executablePath": "C:\\xampp\\php\\php.exe",

php.exeは、XAMPPのインストールフォルダがデフォルトのままであれば、上記のままで使えるはずですが、異なる場合はご自分の環境に書き換えてください。

VS Codeの拡張機能「PHP Debug」

続いて、Visual Stduio Codeの拡張機能「PHP Debug」の導入と設定を行います。

PHP Debugのインストール

PHP Debugについては、「表示」→「拡張機能」からインストールしてください。
拡張機能の導入方法がよく分からない方は、別記事にVS Codeの初期設定についてまとめているのでそちらを参考にしてみてください。

【Laravel】Visual Studio CodeでPHP開発環境を整える手順

以前の記事で、Windowsローカル環境にXAMPPを使ってPHP（8.0）の開発環境を整え、PHPのフレームワークであるLaravel（6.0）のプロジェクトを作る所まで行いました。さっそくLaravelでWEBアプ...

dolphin-review.com

2021.01.18

「launch.json」の作成

PHP Debugをインストールすると、VS Codeの左メニューにデバッグアイコン（虫のようなアイコン）が表示されます（①）。

何かPHPのファイルを適当に一つ、ドキュメントルート配下に作成し（ここではtest.php）、それを開いた状態でこのアイコンをクリックし、「launch.jsonファイルを作成します。」をクリックしてください。

launch.jsonファイルが新規に作られました。
デフォルトで以下のような内容で作成されています。

portの部分は初期作成時は9000で作成されていますが、わたしは上手くいかなかったのでここを9001に書き換えています。
（後で設定をするphp.iniの値と合わせる必要があります）

port部分を書き換えるだけで良いですが、一応configurationsの中身を以下に載せておきます。

	"configurations": [
		{
			"name": "Listen for XDebug",
			"type": "php",
			"request": "launch",
			"port": 9001
		},
		{
			"name": "Launch currently open script",
			"type": "php",
			"request": "launch",
			"program": "${file}",
			"cwd": "${fileDirname}",
			"port": 9001
		}
	]

ちなみに、launch.jsonファイルの実ファイルは、test.phpのファイルと同じ場所に「.vscode」というフォルダが作成され、そこに保存されています。

PHPの拡張機能「XDebug」の導入

VS Code側で行う設定は終わったので、次はPHP側の設定を行います。

まずはXDebugを導入します。

XDebugは環境やバージョンによって使用するdllが変わるので、まずは適切なXDebugを調べるために、phpinfoの情報を取得し、解析サイトで解析してもらいます。

phpinfoをコピー

XAMPP環境の場合、ドキュメントルートの下のdashboardフォルダ配下にデフォルトでphpinfo.phpというファイルがあるので、ブラウザからそのファイルにアクセスします。
もちろん、自分でphpinfo()関数のみを呼び出すphpファイルを作成して実行しても構いません。

上記画面が表示されたら、「Ctrl+A」で全体選択後、「Ctrl+C」で内容をコピーしてください。

もしくは、コマンドラインから以下コマンドを実行しても同じ情報が取得できます。

php -i | clip

適切なXDebugのdllを取得

XDebugのサイトに行きます。

→https://xdebug.org/wizard

コピーしたphpinfoの情報を、テキストエリアの部分（赤枠）に貼り付けて、ページ下部の「Analyse my phpinfo() output」ボタンをクリックします。

すると、解析結果が出力されます。

Xdebug installedがnoとなっている場合、下部に必要なXDebugのバージョンのdllをダウンロードするリンクが表示されているため、それをクリックしてdllファイルを入手します。

Instructionsに記載の手順通り、ダウンロードしたdllファイルを、「c:¥xampp¥php¥ext」に保存します。

その際、ファイル名をphp_xdebug.dllにrenameした上でコピーします。
→（参考）XAMPP – XDebug Setup for PHP 8

php.iniの設定

php.iniファイルを編集します。

XAMPP環境のデフォルトでは、「c:¥xampp¥php¥php.ini」にあります。

末尾に以下の記述を追加します。

[xdebug]
zend_extension = "c:\xampp\php\ext\php_xdebug.dll"
xdebug.idekey=VSCODE
xdebug.client_host=localhost
xdebug.discover_client_host=false
xdebug.client_port=9001
xdebug.mode=debug
xdebug.start_with_request=yes

zend_extensionには、先ほどダウンロードして導入したxdebugのdllファイルへのパスを。
xdebug.client_hostは、VS Codeのlaunch.jsonで指定したport番号を入力します。

設定が不要な項目もあるかもしれませんが、少なくとも下の3つについては記述が必要です。

php.iniの変更が完了したら、XAMPPのコントロールパネルからApacheの再起動をしましょう。

これでデバッグの準備が完了です。

デバッグの実行

さっそくステップ実行をしてみます。

上記の順番でデバッグモードを起動したら、ブラウザで該当phpファイルにアクセスしてみましょう。

タスクバーのVS Codeアイコンが光ります。

VS Codeを開いてみて、設定したブレークポイントがハイライトされ実行が止まっていればOKです。

あとは変数の中身を確認したり、ステップ実行したりと、デバッグしていきましょう。

まとめ

色々なWEBサイトを参考にして設定をしてみましたが、xDebugのバージョンやPHPのバージョンがそれぞれの参考サイトごとに異なり、2時間ほど掛かってようやく動くようになりました。

特にphp.iniの設定と、XDebugのdllファイルの名前を変えたら動くようになりましたので、嵌った方はこのあたりを見直してみると良いかもしれません。

記事の中でも紹介しましたが、以下のサイト（英語）が参考になりました。
→XAMPP – XDebug Setup for PHP 8