Laravel Sail + WSL2 + VSCode でPHPのデバッグを行なう方法【走り書き】

Laravel Sail + WSL2 + VSCode で開発しているときに毎回忘れるデバッグ方法。もう忘れたくないのでここにメモっておきます。

前提

以下の環境を想定してます。

先に要点

備忘録なので先に簡単なまとめ。

VSCodeの準備

PHP Debug 拡張機能のインストール

PHPのデバッグは”Xdebug”というデバッガを利用します。このXdebugを利用するために「PHP Debug」という拡張機能が必要になりますのでインストールしておきます。

参考

PHP Debug – Visual Studio Marketplace

必要なVSCodeの拡張機能はこれだけ。

launch.jsonの作成または追記

VSCodeのデバッグ構成を作成または追記します。

launch.jsonをまだ作成していない場合は「実行とデバッグ」→「launch.jsonファイルを作成します」でデバッガーとして「PHP」を選択することにより基本的な設定が自動的に出来上がります。

すでに他のデバッグ構成が存在する場合はlaunch.jsonを開き、configurationsの内部でCtrl＋Spaceを入力すると構成をサジェストしてくれるので、その中から「{} PHP: Listen for Xdebug」を選びます。

このままではLaravel Sailが属しているネットワークへ外部（今回の場合はブラウザ）から接続できないため、以下のようにしてhostnameを「0.0.0.0」、pathMappingsに以下を追加します。

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

hostnameに関してはWSL2環境でもSailによって作成されたコンテナでも必要になる設定です。hostnameを指定しないとXdebugは127.0.0.1で待ち受けることになり、外部（ホストPCのブラウザなど）からアクセスできなくなるため0.0.0.0を指定します。

pathMappingsの設定はWSL2環境の場合に必要となります。Dev Containerを使ってSailで作成されたコンテナ内で開発をする場合、devcontainer.jsonで/var/www/htmlディレクトリがworkspaceFolderにマッピングされるので設定は不要ですが、WSL2上でSailを使う場合はマッピングされていないためこの設定が必要となります。

ちょっと前のLaravelだったらもうちょっと必要な設定があったけど、今のLaravelだとすでに設定済みみたい。

ブラウザ側の準備

ブラウザ側には「Xdebug helper」という拡張機能を入れます。私はChromeを使っているので以下のものをインストールしました。ブラウザ別に用意されているのでインストールしてください。

参考

Xdebug helper

デバッグの実行

デバッグの実行は「実行とデバッグ」から「Listen for Xdebug」を選択し、処理を止めたいコードにブレイクポイントを仕掛けておけばOK。ブラウザでアプリにアクセスしたタイミングで処理が一時停止します。

処理が止まらない場合、Xdebug helperがDisable（無効）になっている可能性があるため、Webアプリを開いているタブでXdebug helperのアイコンをクリックし、「Debug」を選択します。

まとめ

Xdebugが動かないの根本原因はWSL2＋Sailの仕組みの理解不足に起因します。コンテナ内で127.0.0.1を指定しても外部から接続できないこと、コンテナ内に入って作業しない場合はパスのマッピングをしないとデバッガがデバッグ対象のファイルを見つけられないことを考えればこのような設定になることが分かります。

反射神経でコピペしていた自分に向けての戒めです。