Zenn
Open6

【Laravel11】Sail + DevContainer + Xdebug + debugbarでポータブルな開発環境構築

Docker
Laravel
PHP
VS Code
Xdebug
pconipconi

Laravel Sailで高速にアプリ立ち上げ
VScodeのDevContainerで共有できる実行環境、
Xdebugでブレークポイントを利用したデバッグ、
debugtoolbarで詳細なデバッグ、
が可能な環境構築手順メモです。

pconipconi

1, Laravel環境構築(Sail使用)

Laravelをインストール
今回は公式が用意するSailを使う

curl -s "https://laravel.build/sail_base_post_app?php=82&with=mysql,redis" | bash

<sail_base_post_app>の箇所は今回作成するアプリ名に適宜変更する

デフォルトのmailpit, meilisearchのコンテナ作成は省略
（with=で指定可能）
インストール後、プロジェクトルートへ移動してsail upで立ち上げる

cd sail_base_post_app && ./vendor/bin/sail up

laravel.test-1, mysql-1, redis-1の3つのコンテナが立ち上がるので、
ブラウザでlocalhost確認

これでLaravelインストール完了
sailコマンドのパス通しておくこと

vim ~/.zshrc

// 以下を追記し保存
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

source ~/.zshrc
pconipconi

2, Dev Containerで開く

Dev Containerとは

Visual Studio CodeでDockerコンテナを使用して統一された開発環境を構築し、管理するための機能です。

Dev Container を立ち上げると Docker コンテナに対してホストマシンからソースコードをマウントし、VS Code の拡張機能はコンテナ内にインストールされます。また、VS Code の設定や拡張機能、インストールするライブラリや起動するサービスは devcontainer.json 、Dockerfile 、docker-compose.yml ファイルに定義することができ、これらの設定は Dev Container の起動時に自動で行われます。

https://envader.plus/article/305

Dev Containerの設定をインストールするコマンドがsailで用意されているのでそれを利用する

sail artisan sail:install --devcontainer

DBを選択できるが一旦”mysql”を選択
sailを再起動

sail restart

code .でプロジェクトをVScodeで開き、の左下の風車のようなマークをクリック

「コンテナーを再度開く」をクリック

するとVScodeが再起動され、ローカルではなくコンテナ内でVScodeを開いた状態になる。

VScodeのターミナル箇所でsail@f2a47ca9da05:/var/www/html$ などとなっていればOK.
試しにphp -vやphp artisanが通れば、Dev Containerを利用しコンテナ内でVScodeを開けている。

pconipconi

3, Xdebugを導入する

2つの準備がある。

  • PHP xdebug
  • VScodeの「PHP Debug」

1) PHP xdebugをインストールする

これに関してはSailでインストールしたPHPのバージョンに既に入っているため対応不要。

2) VScodeの拡張機能「PHP Debug」を追加し、ブレークポイントを置けるようにする

VScodeの「実行とデバッグ」タブを開き、青字リンクで「launch.jsonファイルを作成します。」とあるのでそのままクリック
しかし、まだXdebugが入っていないので以下のようになってしまうはず（PHPがない）

なので、コンテナ内で開くVScodeにVScodeの拡張機能を入れる。
.devcontainer/devcontainer.jsonファイルにXdebugを入れて、保存

// devcontainer.json
...

"customizations": {
    "vscode": {
        "extensions": [
            "xdebug.php-debug" // 追記
            // 余裕があればintelephenseやprettierなど入れる
        ],

コンテナを再ビルド。
VScode左下のマークから上部選択肢「コンテナを再ビルドする」を選択。
（時間かかる）
再度、VScodeの「実行とデバッグ」タブ→「launch.jsonファイルを作成します。」
そうすると「デバッガーの選択」の選択肢にPHPが追加されるので、クリック。
すると.vscode/launch.jsonファイルが作成される。
そこに以下を追記。

// launch.json
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {  // 追記
                "/var/www/html": "${workspaceFolder}"
            },
        },

さらに、プロジェクトの.envファイル1行目に以下を追記

SAIL_XDEBUG_MODE=develop,debug,coverage

ここでsailを再起動する必要がある。
「コンテナをローカルで再度開く」だとアプリコンテナしかstopしないので、一旦ローカルのターミナルでsail down→sail up -dが良い。
VScodeの方でももう一度「コンテナで再度開く」
（手順的にもっと省略できそうではある、、）

これで設定が完了したが、この状態でブレークポイントを置いてもまだストップしない。
どうやらremote_autostartがオフだということで、URLパラメータに?XDEBUG_SESSION_START=session_nameをつけてリクエストする必要がある。

https://ドメイン名/パス?XDEBUG_SESSION_START=xxx

ブレークポイントはとりあえず以下に指定

// route/web.php
...
Route::get('/', function () {
    return view('welcome'); // ここにブレークポイント追加
});

Listen for Xdebugでプロセスを起動

ブラウザからは以下のURLを叩く。

http://localhost:8080?XDEBUG_SESSION_START=session_name

そうするとブレークポイントで止まるようになる🌈

2回目以降は、?XDEBUG_SESSION_START=session_nameのパラメータはつけずとも止まる👀

pconipconi

4, laravel-debugbarをインストール

自分自身は正直あまり使わない...💦 が開発に便利なので一応紹介
https://github.com/barryvdh/laravel-debugbar

sail composer require barryvdh/laravel-debugbar --dev

インストール後ブラウザ下部で利用できる

pconipconi

ここまででLaravel開発に便利な環境構築ができる。
Xdebugは必須かと思うのでそこだけ抽出して設定してみても良いと思いますので参考になれば😃