Debugging

API Platform debugging screencast
Watch the Debugging API Platform screencast

デバッグ API プラットフォームのスクリーンキャストを見る

Xdebug

The default Docker stack is shipped without a Xdebug stage. It's easy though to add Xdebug to your project, for development purposes such as debugging tests or remote API requests.

デフォルトの Docker スタックは、Xdebug ステージなしで出荷されます。テストやリモート API リクエストのデバッグなどの開発目的で、プロジェクトに Xdebug を追加するのは簡単です。

Add a Development Stage to the Dockerfile

To avoid deploying API Platform to production with an active Xdebug extension, it's recommended to add a custom stage to the end of the api/Dockerfile.

アクティブな Xdebug 拡張機能を使用して API プラットフォームを本番環境にデプロイしないようにするには、カスタム ステージを api/Dockerfile の最後に追加することをお勧めします。

# api/Dockerfile
FROM api_platform_php as api_platform_php_dev

ARG XDEBUG_VERSION=3.1.3
RUN set -eux; \
 apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
 pecl install xdebug-$XDEBUG_VERSION; \
 docker-php-ext-enable xdebug; \
 apk del .build-deps

Configure Xdebug with Docker Compose Override

Using an override file named docker-compose.override.yml ensures that the production configuration remains untouched.

docker-compose.override.yml という名前の上書きファイルを使用すると、本番構成が変更されないことが保証されます。

As an example, an override could look like this:

例として、オーバーライドは次のようになります。

version: "3.4"

services:
  php:
    build:
      target: api_platform_php_dev
    environment:
      # See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
      # See https://github.com/docker/for-linux/issues/264
      # The `remote_host` below may optionally be replaced with `remote_connect_back`
      # XDEBUG_MODE required for step debugging
      XDEBUG_MODE: debug
      # default port for Xdebug 3 is 9003
      # idekey=VSCODE if you are debugging with VSCode
      XDEBUG_CONFIG: >-
        client_host=host.docker.internal
        idekey=PHPSTORM 
      # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
      # Then PHPStorm will use the corresponding path mappings
      PHP_IDE_CONFIG: serverName=api-platform

Note for Mac environments use the following:

Mac 環境の場合は、次を使用してください。

      XDEBUG_CONFIG: >-
        idekey=PHPSTORM
        client_host=docker.for.mac.localhost

In VSCode, alongside the default PHP configuration in launch.json, you'll need path mappings for the Docker image.

VSCode では、launch.json の既定の PHP 構成と共に、Docker イメージのパス マッピングが必要になります。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "log": true,
            "pathMappings": {
                "/srv/api": "${workspaceFolder}/api"
            },
        },
    ]
}

Note: For Linux environments, the client_host setting of host.docker.internal will not work, you will need the actual local IP address of your computer.

注: Linux 環境では、host.docker.internal の client_host 設定は機能しません。コンピューターの実際のローカル IP アドレスが必要になります。

Troubleshooting

Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.

次のコマンドでインストールを検査します。要求された Xdebugversion が出力に表示されるはずです。

$ docker compose exec php \
    php --version

PHP …
    with Xdebug v3.1.3, Copyright (c) 2002-2021, by Derick Rethans
    …