WSL2, Laravel Sail 環境でXdebugを有効にする

Background

最近laravel sailをよく使うが、xdebug環境を整えたことがなかった。
php artisan serveを使わない方法を調べてもなかなか解決しなかったのでまとめ。

Environment

• wsl2, ubuntu
• PHP 8.2.8, laravel 10.14.1
• Xdebug v3.2.1

Solution

※sailでアプリケーションディレクトリ作成後からの内容になります。
編集対象のファイルは以下の4つ。

• php.ini
• docker-compose.yml
• .env
• launch.json

php.ini

通常はvendor配下に存在しているので、以下コマンドでアプリフォルダ直下に持ってきます。

• wslで実行
  • ./vendor/bin/sail sail:publish
• container内で実行
  • php artisan sail:publish
    コマンド実行するとアプリディレクトリ直下にdockerフォルダが作成されます。
    中身はこんな感じ

-docker/
  -8.0/
  -8.1/
  -8.2/
    -Dockerfile
    -php.ini
    -start-container
    -supervisord.conf

php.iniに以下を追加

[xdebug]
zend_extension = xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = true
xdebug.idekey = VSC
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

Dockerfileの以下の箇所で配置されています

COPY php.ini /etc/php/8.2/cli/conf.d/99-sail.ini

docker-compose.yml

docker-compose.ymlのservecesのアプリコンテナ(デフォルトではlaravel.test)に以下の内容にする
(直接変更した箇所はportsに9003:9003を追加しただけ。depends_onはアプリ作成時に選択したサービスによって変わる。)

    laravel.test:
        build:
            context: ./docker/8.2
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.2/app
        extra_hosts:
            - 'host.docker.internal:host-gateway'
        ports:
            - '${APP_PORT:-80}:80'
            - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
            - '9003:9003'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
            IGNITION_LOCAL_SITES_PATH: '${PWD}'
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
        depends_on:
            - mysql
            - redis
            - selenium

.env

.evnファイル2以下を追加。docker-compose.ymlで環境変数を渡す。

SAIL_XDEBUG_MODE=debug

launch.json

アプリフォルダ直下の.vscodeフォルダのlaunch.jsonを編集。
ファイルが存在しない場合はRun -> Add ConfigurationでPHPを選択してファイル作成。(サイドバーのデバッグから作成も可)
ファイル内容は以下

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

Confirmation

1. F5キーを押してデバッグモードを起動
2. web.phpなどデバッグしたい場所にブレイクポイントを設置
3. http://localhost に接続
   上記の手順で設定に問題なければ止まってくれると思います。
   

Conclusion

laravel公式のやり方でやると、php artisan serveコマンド実行しないとできなかった。
ネットで探した情報で試してもなかなかうまく行かず。
同じように困っている人の参考になれば。