2020-10-16 13:08:20 +02:00
# Installing Xdebug
2021-12-22 12:06:26 +01:00
The default Docker stack is shipped without [Xdebug ](https://xdebug.org/ ),
a popular debugger and profiler for PHP.
It's easy, though, to add it to your project.
2020-10-16 13:08:20 +02:00
## 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
# Dockerfile
2021-12-15 15:58:20 +01:00
FROM symfony_php AS symfony_php_debug
2020-10-16 13:08:20 +02:00
2021-12-22 12:06:26 +01:00
ARG XDEBUG_VERSION=3.1.2
2020-10-16 13:08:20 +02:00
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
2021-06-18 18:47:07 +02:00
Using an [override ](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files ) file named `docker-compose.debug.yml` ensures that the production
2020-10-16 13:08:20 +02:00
configuration remains untouched.
2021-12-22 12:06:26 +01:00
As an example, an override could look like this:
2020-10-16 13:08:20 +02:00
```yaml
2021-06-18 18:47:07 +02:00
# docker-compose.debug.yml
2020-10-16 13:08:20 +02:00
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
2020-12-18 11:16:37 +00:00
# The `client_host` below may optionally be replaced with `discover_client_host=yes`
2020-12-21 17:42:57 +00:00
# Add `start_with_request=yes` to start debug session on each request
2020-10-16 13:08:20 +02:00
XDEBUG_CONFIG: >-
2020-12-18 11:16:37 +00:00
client_host=host.docker.internal
XDEBUG_MODE: debug
2020-10-16 13:08:20 +02:00
# 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
2021-12-22 12:06:26 +01:00
extra_hosts:
# Ensure that host.docker.internal is correctly defined on Linux
- host.docker.internal:host-gateway
2020-10-16 13:08:20 +02:00
```
2021-12-22 12:06:26 +01:00
Build your image with your fresh new XDebug configuration:
2021-06-18 18:47:46 +02:00
```console
2022-07-28 19:01:17 +02:00
docker compose -f docker-compose.yml -f docker-compose.debug.yml build
2021-06-18 18:47:46 +02:00
```
2020-10-16 13:08:20 +02:00
Then run:
2021-06-14 15:12:18 +02:00
```console
2022-07-28 19:01:17 +02:00
docker compose -f docker-compose.yml -f docker-compose.debug.yml up -d
2021-06-14 15:12:18 +02:00
```
2020-10-16 13:08:20 +02:00
2021-06-23 10:36:31 +02:00
## Debugging with Xdebug and PHPStorm
You can use the **Xdebug extension** for [Chrome ](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc ) or [Firefox ](https://addons.mozilla.org/fr/firefox/addon/xdebug-helper-for-firefox/ ) if you want to debug on the browser (don't forget to configure it).
2021-06-18 18:47:46 +02:00
2021-12-22 12:06:26 +01:00
If you don't want to use it, add on your request this query param: `XDEBUG_SESSION=PHPSTORM` .
2021-06-18 18:47:46 +02:00
2021-12-22 12:06:26 +01:00
On PHPStorm, click on `Start Listening for PHP Debug Connections` in the `Run` menu.
2021-06-18 18:47:46 +02:00
2021-06-23 10:36:31 +02:00
Otherwise, you can create a [PHP Remote Debug ](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html ) configuration with the following parameters:
* Server:
2021-12-22 12:06:26 +01:00
* 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`
2021-06-23 10:36:31 +02:00
2021-06-18 18:47:46 +02:00
You can now use the debugger.
2020-10-16 13:08:20 +02:00
## Troubleshooting
2021-12-22 12:06:26 +01:00
Inspect the installation with the following command. The Xdebug version should be displayed.
2020-10-16 13:08:20 +02:00
2021-06-14 15:12:18 +02:00
```console
2022-07-28 19:01:17 +02:00
$ docker compose exec php php --version
2021-06-14 15:12:18 +02:00
PHP ...
2021-12-22 12:06:26 +01:00
with Xdebug v3.1.2 ...
2021-06-14 15:12:18 +02:00
```