laravelプロジェクトで
ブレークポイントをおいてデバッグ実行する方法が
直感的にわからなくて
手順がほしかったときに書いたものです

環境

macOS Sonoma v14.5
docker desktop for mac v4.37.2
vscode

前提

sailを利用してプロジェクトが作成済みであること
プロジェクト作成についてはこちらを参考にしました
https://laravel.com/docs/11.x/installation#sail-on-macos

コンテナを起動していないこと

コンテナを起動していた場合、コンテナは削除する

# 起動しているコンテナ一覧
docker ps
# コンテナ削除
sail down

デバッグ実行する

1. vscode拡張機能をインストール

2. .vscode/launch.jsonを作成

以下を追加

.vscode/launch.json

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

2. .envに追加する

.env

+ SAIL_XDEBUG_MODE=debug

3. コンテナを起動する

sail up -d

4. デバッグできることを確認する

テストコードにブレークポイントを置く
行左端をクリックして赤丸が表示されるとブレークポイントが置けた状態です

テスト実施

sail debug test ./tests/Feature/ExampleTest.php

ブレークポイントで止まります

補足

.vscode/launch.jsonに記載したpathMappingsをもとにデバッグするため、vscodeで開いているフォルダがlaravelプロジェクト直下(この場合、example-appフォルダ)
でない場合、ブレークポイントで止まらないです。
なおターミナル上でフォルダ移動してもブレークポイントが止まらないです

それでもブレークポイントが止まらない場合、
launch.jsonのpathMappingを変更してみるとうまくいくことがあります

// 絶対パスを直接入力
            "pathMappings": {
            　// "コンテナ側のパス": "ローカル側のパス"
+                "/var/www/html": "/your/work/path/to"
            },

debugと指定せずに実行するとデバックモードに関係なく、ブレークポイントで止まらず実行されます

# デバックモードで起動中のコンテナに対してステップ実行せずにテストする
sail artisan test ./tests/Feature/ExampleTest.php

workspaceRoot は非推奨となったようです
https://code.visualstudio.com/docs/editor/variables-reference#_why-isnt-workspaceroot-documented

    "pathMappings": {
        // "コンテナ側のパス": "ローカル側のパス"
+          "/var/www/html": "${workspaceRoot}"
    },