Visual Studio Code（VS Code）で PHP を書いていて、変数の中身を見ながら止めたい・一行ずつ進めたい、というときの最低限のセットアップ覚え書きです。新しいフォルダを開くたびに launch.json をどう書いたか忘れるので、自分用のメモとしても使います。
この記事でできること
- ブラウザや CLI から動かしている PHP の処理にブレークポイントを置いて止められるようにする
- VS Code の
.vscode/launch.jsonに、よく使うデバッグ設定を置いておく
前提になるもの
- PHP が動く環境（ローカルに PHP、または WSL・Docker 上の PHP など）
- PHP に Xdebug 拡張が入っていること（
php -mでxdebugが出るか、php -iで Xdebug の行があるかで確認） - VS Code の拡張機能 PHP Debug（Felix Becker 版、ID:
xdebug.php-debug）を入れておくこと
Xdebug はメジャーバージョンで設定キーが変わっています。Xdebug 2 ではデバッグ用の待ち受けポートがよく 9000、Xdebug 3 以降では既定が 9003 です。php.ini（または conf.d 下の *.ini）と、後述の launch.json の port を同じ番号に揃えてください。
Xdebug 側（php.ini）の例
環境に合わせて調整します。コピペの前に、すでに Xdebug のブロックがあるか確認し、重複しないようにしてください。
Xdebug 3 系のイメージ
zend_extension=xdebug
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1
ブラウザでページを開いたときだけデバッグを付けたい場合は、xdebug.start_with_request=trigger とし、拡張機能やブラウザ用アドオンで「デバッグ開始」を合図する運用もよく使われます。
Xdebug 2 系のイメージ（参考）
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
launch.json を置く場所
ワークスペース（開いているフォルダ）直下に .vscode フォルダを作り、その中の launch.json に書きます。VS Code の「実行とデバッグ」ビューから「構成の追加」でも雛形を作れます。
launch.json の中身（基本形）
次の 2 つの構成が入っていれば、多くのローカル開発で足ります。
- Listen for Xdebug … Web から PHP を実行するときなど、すでに動いている PHP に Xdebug が接続してくるのを VS Code が待ち受けるモードです。ブラウザでページを開いてブレークポイントで止めたいときに使います。
- Launch currently open script … 今エディタで開いている PHP ファイルを CLI として起動し、そこでデバッグします。コマンドライン用の小さなスクリプトを試すときに便利です。
ポートは環境に合わせて 9003（Xdebug 3 想定）か 9000（Xdebug 2 想定）にしてください。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9003
}
]
}
Docker や別マシンで動かしているとき
PHP がコンテナ内で動いていて、ソースはホストの VS Code で開いている場合などは、pathMappings が必要になることがあります（コンテナ内のパスとローカルのパスの対応）。接続できないときは、PHP Debug 拡張のドキュメントに沿って pathMappings を足すのが定石です。
動作確認の流れ（Web の場合）
- PHP に Xdebug が有効で、ポートが
launch.jsonと一致していることを確認する - VS Code で「Listen for Xdebug」を選び、緑の実行ボタンでデバッグを開始（待ち受け状態になる）
- PHP ファイルにブレークポイントを置く
- ブラウザでそのコードが実行される URL にアクセスする
- ブレークポイントで止まれば成功
うまく止まらないときに見るところ
- ポート番号が Xdebug と VS Code で食い違っていないか（9000 と 9003 の取り違えが多いです）
- 別プロセスが同じポートを掴んでいないか
php.iniを直したあと、Web サーバー／PHP-FPM を再起動したか- CLI 用の
php.iniと Web 用のphp.iniが別ファイルで、編集している方と実際に動いている方が違わないか（php --iniやphpinfo()で確認）
元記事の設定（ポート 9000）について
この記事を最初に書いた当時のメモでは、次のように ポート 9000 の構成をそのまま貼っていました。今でも Xdebug 2 を 9000 で使っている環境ならそのまま有効です。Xdebug 3 に移行している場合は、上の例のように port と php.ini を 9003 側に揃えるのが安全です。
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9000
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9000
}
]
}
まとめ
VS Code で PHP をデバッグするには、Xdebug の有効化と PHP Debug 拡張、そして .vscode/launch.json の 3 点セットが中心です。ポート番号と php.ini の組み合わせさえ合っていれば、「これでいけるはず」が再現しやすくなります。環境が変わったら、この記事のチェックリストを上から順に確認すると早いです。
コメント