VSCode + Docker + PHP の開発環境を、XDebugでデバッグする。

はじめに

扱っていたプロジェクトは Laravel を使ったPHPアプリケーションで、VSCodeによって製作されていました。
Java や Swift を使った作業には慣れていたのですが、PHPのデバッグが久しぶりで大いにはまったので備忘録です。

やったこと

PHPのデバッグには XDebug を使うということなので、XDebug解説記事 をふむふむと読み（大変わかりやすい記事です）作業に当たりました。

たくさんの記事が丁寧に説明しているので詳細は端折りますが

php.ini

;...省略

[XDebug]
zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so
xdebug.default_enable=1
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.remote_handler=dbgp
xdebug.remote_connect_back=0
xdebug.remote_host=host.docker.internal
xdebug.remote_log=/tmp/xdebug.log
xdebug.idekey=VSCODE

Dockerfile

FROM php:7.4-apache

# XDebug
RUN pecl install xdebug \
  && docker-php-ext-enable xdebug

#...省略

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}/src"
      },
      "ignore": [
          "**/vendor/**/*.php"
      ]
    }
  ]
}

こんな感じで、PHP初期化、Docker初期化、XCodeのデバッグ設定を終えました。

これが全然びくとも動かない。

解決策

いろんなパラメータをいじり倒しましたが全然動かず諦めかけましたが、最終的には xdebug のバージョンの問題ということに気づきました。

$ php -v | grep -i "xdebug"
    with Xdebug v3.0.2, Copyright (c) 2002-2021, by Derick Rethans

Xdebug 2.x から 3.x で、設定値が様変わりしています。
https://xdebug.org/docs/upgrade_guide
このドキュメントに詳しくわかりやすく書いてあります。

たとえば、xdebug.remote_log は xdebug.log に Rename されています。どうりで、ログもさっぱり出ないわけです。

細かい意味はそちらを見ていただくとして、上記の php.ini は正しくはこうなりました。

php.ini

;...省略

[XDebug]
zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so
xdebug.mode=debug
xdebug.client_port=9000
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log=/tmp/xdebug.log

現場からは以上です。