Laravel SailでXdebugを使う設定

PHPのWebフレームワークLaravelにはLaravel SailというDockerを利用した開発環境があります。コマンド一発で新しい開発環境が簡単に作れて大変すばらしいですね。

今回は、Windows(WSL2)でLaravel Sail+Xdebug+VSCodeを使ってステップデバッグをしようとしたときに、中々ブレークポイントで止まってくれなかったのでその設定を記事にしたいと思います。

実行環境

Windows10Pro バージョン21H1
DockerDesktop Version 4.2.0 (70708)
Ubuntu 20.04.3 LTS（WSL2にインストール）
laravel/sail 1.0.1
VSCode 1.62.2

.envファイル

Laravel Sailで開発環境を構築するとXdebugはあらかじめインストールされています。公式ドキュメントによると、.envファイルに変数を設定することで、Xdebugが有効になると書かれています。

https://laravel.com/docs/8.x/sail#debugging-with-xdebug

開発環境を一度、sail downして.envファイルに以下の変数を追記します。

SAIL_XDEBUG_MODE=develop,debug

sail up -dで開発環境を起動します。

以前のDockerDesktopではWSL2でdocker-composeを実行するとXdebugとVSCodeの通信がうまくいきませんでした。現在のバージョンではPHPのxdebug.client_hostにIPアドレスを開発環境の起動の度に設定しなくとも動くようになっています。

PHP Debug

次にVSCodeにPHP Debugをインストールします。

https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug

インストールしたらLaravel Sailのルートディレクトリに.vscodeディレクトリを作成して中にlaunch.jsonを作成します。内容は以下を参考にしてください。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "hostname": "localhost",
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        },
    ]
}

F5キーを押すかメニューからデバッグを開始を選んでデバッグを開始します。これで、VSCodeがXdebugからデバッグ接続を受けることができるようになります。

XdebugCLIを実行してVSCodeにPHP Debugが正しくインストールされているか確認します。もしも以下のようなエラーが出る場合は、どこかが間違っているかWSLの不調が起きている可能性があります。WSLを再起動してもう一度試してみてください。

$ sail debug migrate
Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(
Nothing to migrate.
Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(
Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(

WSLの再起動はPowerShellで以下のコマンドを実行します。

> wsl --shutdown

Xdebug Helper

ウェブアプリのデバッグをするためにウェブブラウザに拡張機能をインストールします。

https://xdebug.org/docs/step_debug#web-application

インストールしたらlocalhostを開いているタブでXdebug HelperをDebugモードにします。これで、開発環境のXdebugがトリガーを受け取ることができるようになります。

以上の設定で、ステップデバッグが利用可能になりました。VSCodeでPHPのコードにブレークポイントを設定したら、ブラウザからリクエストを送ってください。コードの実行がVSCodeでブレークポイントを打った箇所で一時停止されます。

記事の著者：tnk

• Docker
• laravel
• PHP
• VSCode
• WSL2
• Xdebug

この記事をSNSでシェアする！