Dockerで構築したLaravelの開発環境にXdebugを導入する

新規プロジェクトにアサインされた際ソースコードがどのように実行されているかを迅速に把握することが必要となります。
ソースコードを１から読むことも必要ですが、デバッガを使用しどのように動いているかを把握することで、仕様理解が一気に進みます。

私は今までいくつかの案件で環境構築をさせていただく機会があり、その中でもXdebug導入で何度も躓くことがありました。
そういった経験から得られた知見をまとめ、今後詰まった時の参考にするためまとめます。

環境

• php 8
• Laravel 8
• Xdebug v3.1.5
• Visual Studio Code 1.71.2

Xdebugのバージョンについて

今回はバージョン３をインストールする

Xdebug導入について検索するとバージョン2と3の情報がヒットするが、全く記法が異なるので注意
自分が導入したいバージョンについて検索すること

バージョンによる記法の違いは以下を参照

Xdebugをインストール

VSCodeでXdebugをインストール

ファイルの編集

Laravelインストール用のDockerfile

FROM php:8.0.8-apache
 (略)
RUN apt-get update \
 (略)
  && pecl install xdebug \  ←追加
  && docker-php-ext-enable xdebug　←追加
(略)
WORKDIR /var/www/html/

php.ini

[xdebug]
xdebug.client_host = host.docker.internal
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = 0
xdebug.client_port = 9005
xdebug.log=/tmp/xdebug.log

xdebug.client_portは後述するlaunch.jsonのport指定と合わせる

launch.jsonにXdebugの設定追加

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "hostname": "0.0.0.0",
            "port": 9005,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}/src"
            }
        },

pathMappingをよく間違えるので注意
${workspaceRoot}はプロジェクトのルートなので、Docker関連のディレクトリが存在していることがある
Laravelのディレクトリ(今回はsrc)を指定すること

使ってみる

実際の使い方は以下の動画を参考

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

そもそもインストールされているかを確認

docker compose exec (docker composeで指定するサービス名) /bin/bash
root@aaaaaaaa:/var/www/html# php -v
PHP 8.0.8 (cli) (built: Jul 22 2021 02:26:57) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.8, Copyright (c) Zend Technologies
    with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans

Xdebugと書かれていない場合はインストールされていない
Dockerfileを確認する

ログを確認する

今回だと/tmp/xdebug.logにログが出る設定にしている
Laravelコンテナにアタッチし、該当のログファイルを確認する

docker compose exec (docker composeで指定するサービス名) /bin/bash
root@aaaaaaaa:/var/www/html# cd /tmp
root@aaaaaaaa:/tmp# ls -a
.  ..  xdebug.log
root@aaaaaaaa:/tmp# cat xdebug.log
・
・
・

参考