【Laravel】laradockでXdebugを使えるようにするためのメモ

1 laradockにXdebugをセットアップする
- 1.1 laradockの設定
- 1.2 VSCodeの設定
  - 1.2.1 launch.json

laradockにXdebugをセットアップする

laradockを使ったLaravelの開発環境でPHPデバッガのXdebugを使用するための設定方法をメモします。
なお、今回の記事におけるlaradock環境はnginx & php-fpmの構成でIDEはVSCodeを使用します。

2024年2月時点でlaradockはあまり使われていないようですが、古いプロジェクトなどで環境を合わせる際などに参考にしてみてください。
（laradockの基本事項については本記事では触れていません）

laradock公式サイト
https://laradock.io/

以降の手順は大きく分けて、laradockの設定ファイルの編集、VSCodeの設定の2つになります。

laradockの設定

laradockの設定ファイル laradock/.env を開いてPHP_FPMの設定箇所を見つけます。

こちらより、以下の2つの項目を次のように設定します。

PHP_FPM_INSTALL_XDEBUG=true

PHP_FPM_XDEBUG_PORT=9003

後者のポート番号は任意ですが、この次に行うXdebugの設定と合わせる必要があります。

また、同ファイル内、WORKSPACEの設定箇所にも同様にXDEBUGの箇所がありますが、上記のPHP_FPMの部分だけ変更すればOKです。

次に、laradock/php-fpm/xdebug.ini を開いてXdebugの設定を記述します。

xdebug.client_host = host.docker.internal
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.remote_handler = "dbgp"
xdebug.client_port = 9003

デフォルトで記載されている内容がXdebugバージョン2系での設定方法でしたが、php-fpmビルド時にインストールされる（※）Xdebugのバージョンが3系であったため、上記のように3系の設定内容に書き換える必要があります。

laradock/workspace配下にも同じxdebug.iniが存在していますが、こちらは設定を変える必要はありません。

設定が完了したら、コンテナを再ビルド〜起動し直します。

docker-compose up -d php-fpm nginx

※本記事 2024年2月時点

VSCodeの設定

コンテナ側でXdebugの導入が完了したら、次はVSCodeでXdebugを使えるようにしていきます。

Xdebug使用にあたり、あらかじめ拡張機能「PHP Debug」をVSCodeに追加しておく必要があります。

拡張機能のインストールと、これから設定するlaunch.jsonの作成方法は以下記事で詳しく説明していますのでご参照ください。

【PHP 8】Xdebug + Docker + VSCodeによるデバッグ環境構築

launch.json

.vscode/launch.jsonにXdebugの設定を行いますが、
laradockのディレクトリとLaravelのプロジェクト本体をひとまとめにしたパスがVSCodeのプロジェクトルートという構成を前提としています。

.
├── .vscode
│   └── launch.json
├── Laravelのプロジェクト
└── laradock

.vscode/launch.json

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

portの指定を先に行なったxdebug.iniの設定と一致させて、pathMappingsの項目で、nginxコンテナの/var/wwwとVSCodeプロジェクトルートをマッピングさせればOKです。

こちらで準備が整いましたのであとはデバッガを起動し、Laravelプロジェクトのソースコードの任意の箇所にブレークポイントを貼ってブラウザからアクセスし、ブレークポイントの箇所で処理が止まれば成功です。

Follow me!