Linknet Engineers Blog

Laravel Sail + WSL2 + Visual Studio Codeでステップ実行する

2023/02/20

吉川

こんにちは。株式会社リンクネットソリューション事業部の吉川です。

弊社のWeb開発で使用頻度が高いのがLaravelです。
最近のLaravel Sailでは最初からXdebugが入っており、簡単に使えるようになっています。
すごく便利で、ぜひお薦めしたいので、Xdebugでステップ実行するための設定をまとめようと思います。

■ 環境

OS: windows11
エディタ: Visual Studio Code（以下vscode）
ブラウザ: GoogleChrome

$ sail artisan -V
Laravel Framework 9.52.0

$ sail php -v
PHP 8.2.3 (cli) (built: Feb 14 2023 16:58:12) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.3, Copyright (c) Zend Technologies
    with Zend OPcache v8.2.3, Copyright (c), by Zend Technologies
    with Xdebug v3.2.0, Copyright (c) 2002-2022, by Derick Rethans

■ 拡張機能

ブラウザとvscodeに拡張機能をインストールします。

GoogleChrome

Xdebug helper
デバッグモードにするかをブラウザ側で任意に決めるため使用します。
chromeのストアページ: https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc

vscode

Remote Development
WSL上のフォルダやファイルを直接vscodeで開くための拡張機能です。
PHP Debug
Xdebugを使用するための拡張機能です。
こちらはWSL側のvscodeにインストールします。

■ 設定

docker-compose.ymlと.envに追記します。
PHP_IDE_CONFIGはコマンドラインから実行するプログラムのデバッグに使用します。

docker-compose.yml

        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
+            PHP_IDE_CONFIG: serverName=0.0.0.0
        volumes:
            - '.:/var/www/html'

.env

APP_DEBUG=true
APP_URL=http://localhost

+SAIL_XDEBUG_MODE=debug,develop

環境変数を読み直すためdocker環境を再起動します。

$ sail down
$ sail up -d

次に、vscodeのデバッグ構成を作成します。
サイドメニューの「実行とデバッグ」を開き、「launch.json ファイルを作成します」をクリックします。
拡張機能のPHP Debugが正しくインストールされていれば、デバッガーの選択リストにPHPがあるので選択します。
alt デバッガー選択

生成されたlaunch.jsonのうち、Xdebugからリッスンする設定の部分を編集します。
ここで、hostnameの値はdocker-compose.ymlに記載したPHP_IDE_CONFIGの値と同じにする必要があります。

launch.json

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

以上で一通りの設定は完了です。

■ ステップ実行

Web画面のステップ実行とコマンドラインプログラムのステップ実行で操作が異なります。
いずれにしても、まずはデバッグを開始します。
デバッグ構成があると「実行とデバッグ」サイドパネルの内容が変わっています。
今回はリストから「Listen for Xdebug」を選択し、左にある三角形のボタンをクリックします。
alt デバッグの開始

Web画面

まずは開発環境のURLにアクセスし、Xdebug Helper拡張機能でデバッグを有効にします。
後はブレークポイントを設定して画面をリロードします。

コマンドラインプログラム

Web画面の時と同じようにブレークポイントを設定します。
普段は

$ sail artisan migrate

のように実行しているところを、

$ sail debug migrate

として実行するとブレークポイントで止まるようになります。

■ ブレークポイントで止まらないとき

もろもろの設定をしてもブレークポイントで止まってくれないことが多々あります（個人的感想）。
これまでに出会った止まらない原因を挙げておきます。

9003番ポートが使用できない
Xdebugがデフォルトで使用するポートは9003ですが、別のエディタなど、他のプログラムが既に使っていると接続できずうまく動きません。
他のプログラムを終了するか、そのプロジェクトでXdebugが使用するポートを変える必要があります。
コマンドラインから実行したときのみ止まらない
launch.jsonのhostnameとdocker-compose.ymlのPHP_IDE_CONFIGのserverNameが合っていない可能性があります。
2つの値が異なっていると止まってくれません。

■ 最後に

Xdebugのステップ実行はとても便利ですが、いざ使おうとするとハマることが多い気がします。
それでもdd()などで都度確認するのは大変なので、少し時間がかかっても快適に開発できる環境を整えられたらいいなと思います。

前の記事次の記事