Skip to content

Latest commit

 

History

History
97 lines (72 loc) · 3.25 KB

xdebug.md

File metadata and controls

97 lines (72 loc) · 3.25 KB
Raw

Installing Xdebug

The default Docker stack is shipped without Xdebug, a popular debugger and profiler for PHP. It's easy, though, to add it to your project.

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.1.2
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 an 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
    extra_hosts:
      # Ensure that host.docker.internal is correctly defined on Linux
      - host.docker.internal:host-gateway

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, add on your request this query param: XDEBUG_SESSION=PHPSTORM.

On PHPStorm, click on Start Listening for PHP Debug Connections in 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 Xdebug version should be displayed.

$ docker-compose exec php php --version

PHP ...
    with Xdebug v3.1.2 ...