WSL2 + ddev の Drupal 環境で xdebug を有効化する

環境

• Windows 11
• DDEV
• Drupal 11
• VSCode

前提

• DDEV 環境で、 Drupal のセットアップ済み
• xdebug helper などのデバッガをインストール済み

やりたいこと

WSL2 + ddev の Drupal 環境で xdebug を有効化し、 debug を行う。

ブレークポイントを設定し、変数などを確認する。

手順

config.yaml の更新

.ddev/config.yaml に、下記設定する。

xdebug_enabled: true

name: drupal11
type: drupal11
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
xdebug_enabled: true
additional_hostnames: []
additional_fqdns: []
...

php-xdebug.ini の作成

.ddev/php のディレクトリ内に、 php-xdebug.ini を作成する。

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=10.255.255.254
xdebug.client_port=9003

xdebug.client_host のアドレスは、 /etc/resolv.conf を参照し、設定されている nameserver の IPアドレスを指定する。

tarohida@tarohida-l13:~/projects/drupal11$ cat /etc/resolv.conf 
# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
# [network]
# generateResolvConf = false
nameserver 10.255.255.254

VSCode 側の設定

「PHP Debug」の拡張をインストールしておく。

.vscode/launch.json を作成する。

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

設定読み込み

ddev start で環境を起動する、もしくは ddev restart で環境を再起動し、設定の変更を読み込む。

動作確認

web/index.php にブレークポイントを設定

デバッグを開始。

ブラウザ側で、デバッガを有効にした状態でサイトにアクセス。

ここでは、xdebug helper を利用している。

すると、以下のようにブレークポイントで処理が止まる。

この先は、処理を少しずつ進めたり、変数を確認したり、好きにデバッグしていけばよい。

よくあるトラブル (自分がハマったやつ)

このように、ブレークポイントがグレーアウトして止まってくれないときは、 "pathMapping" の設定がおかしい。

リクエストは VSCode 側で認識されているのに、止まっていないということなので。