Skip to content

Latest commit

 

History

History
93 lines (68 loc) · 3.23 KB

xdebug.md

File metadata and controls

93 lines (68 loc) · 3.23 KB
Raw

Installing 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 API requests remotely.

Add a Debug Stage to the Dockerfile

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

# Dockerfile
FROM symfony_php as symfony_php_debug

ARG XDEBUG_VERSION=3.0.4
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.debug.yml ensures that the production configuration remains untouched.

As example, an override could look like this:

# docker-compose.debug.yml
version: "3.4"

services:
  php:
    build:
      context: .
      target: symfony_php_debug
    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 `client_host` below may optionally be replaced with `discover_client_host=yes`
      # Add `start_with_request=yes` to start debug session on each request
      XDEBUG_CONFIG: >-
        client_host=host.docker.internal
      XDEBUG_MODE: debug
      # 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=symfony

Build your image with your fresh new xdebug configuration:

docker-compose -f docker-compose.yml -f docker-compose.debug.yml build

Then run:

docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d

Debugging with Xdebug and PHPStorm

You can use the Xdebug extension for Chrome or Firefox if you want to debug on the browser (don't forget to configure it).

If you don't want to use it, just add on your request this query param: XDEBUG_SESSION=PHPSTORM.

On PHPStorm, you just have to click on the button Start Listening for PHP Debug Connections on the Run menu.

Otherwise, you can create a PHP Remote Debug configuration with the following parameters:

  • Server:
    • Name: symfony (must be the same as defined in PHP_IDE_CONFIG)
    • Host: https://localhost (or the one defined with SERVER_NAME)
    • Port: 443
    • Debugger: Xdebug
    • Absolute path on the server: /srv/app
  • IDE key: PHPSTORM

You can now use the debugger.

Troubleshooting

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

$ docker-compose exec php php --version

PHP ...
    with Xdebug v3.0.4 ...