Docker コンテナ中で動いている PHP をホストの macOS 上の VSCode でデバッグするための備忘録. ここでは PHP 7.4.30 を PHP-FPM のコンテナで動かしているとする.

まずはコンテナ中に Xdebug をインストール.

Dockerfile
FROM php:7.4.30-fpm-bullseye
...
RUN pecl install xdebug
...

次に Xdebug の設定ファイルを作成する. xdebug.client_host には VSCode が動作しているホストのアドレスをセットする. Docker Desktop for Mac では host.docker.internal という名前でコンテナ内からホストを参照することができる. なお xdebug.client_port にはホストの IP アドレスを指定するが、この値は後述する VSCode 側でのポートの設定と一致させる必要がある.

docker-php-ext-debug.ini
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
;xdebug.discover_client_host=1
xdebug.client_port=9003

作成した Xdebug の設定ファイルをコンテナ内にマウントするように docker-compose.yml を作成する.

docker-compose.yml
services:
  my-service:
    ...
    volumes:
      - type: bind
        source: ./docker-php-ext-xdebug.ini
        target: /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

VSCode 側ではまず PHP のデバッグのための拡張機能が必要となる. ここでは PHP-Debug を https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug 使用する. 拡張機能インストール後、 実行 / デバッグ用の構成ファイル .vscode/launch.json を編集し、以下のように設定する.

vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/コンテナ内のプロジェクトディレクトリへのパス": "${workspaceRoot}"
            }
        },
        ...
    ]
}

ここで設定した port の値は先述の docker-php-ext-debug.ini で設定した値と一致させる必要がある.

ここまで準備できたら VSCode 上で Listen for Xdebug を実行し、 docker compose up -d でコンテナを起動させることができる. VSCode 上でブレークポイントを入れておくと、ユーザーからのリクエストを受けたタイミングでデバッガが PHP コードの実行をブレークポイントの地点で停止させてくれるようになる.

References