2022-08-04 14:47:59 +02:00
# Using Xdebug
2020-10-16 13:08:20 +02:00
2022-08-04 14:47:59 +02:00
The default development image is shipped with [Xdebug ](https://xdebug.org/ ),
2021-12-22 12:06:26 +01:00
a popular debugger and profiler for PHP.
2020-10-16 13:08:20 +02:00
2022-08-04 14:47:59 +02:00
Because it has a significant performance overhead, the step-by-step debugger is disabled by default.
It can be enabled by setting the `XDEBUG_MODE` environment variable to `debug` .
2020-10-16 13:08:20 +02:00
2022-08-04 14:47:59 +02:00
On Linux and Mac:
2020-10-16 13:08:20 +02:00
```
2022-08-04 14:47:59 +02:00
XDEBUG_MODE=debug docker compose up -d
2020-10-16 13:08:20 +02:00
```
2022-08-04 14:47:59 +02:00
On Windows:
2021-06-18 18:47:46 +02:00
```
2022-08-04 14:47:59 +02:00
set XDEBUG_MODE=debug& & docker compose up -d& set XDEBUG_MODE=
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
2022-08-04 14:47:59 +02:00
First, [create a PHP debug remote server configuration ](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html ):
2021-06-18 18:47:46 +02:00
2022-08-04 14:47:59 +02:00
1. In the `Settings/Preferences` dialog, go to `PHP | Servers`
2. Create a new server:
2022-10-05 10:46:47 +02:00
* Name: `symfony` (or whatever you want to use for the variable `PHP_IDE_CONFIG` )
2022-08-04 14:47:59 +02:00
* Host: `localhost` (or the one defined using the `SERVER_NAME` environment variable)
* Port: `443`
* Debugger: `Xdebug`
* Check `Use path mappings`
2023-09-20 16:53:05 +02:00
* Absolute path on the server: `/app`
2021-06-18 18:47:46 +02:00
2022-08-04 14:47:59 +02:00
You can now use the debugger!
2021-06-23 10:36:31 +02:00
2022-08-04 14:47:59 +02:00
1. In PHPStorm, open the `Run` menu and click on `Start Listening for PHP Debug Connections`
2. Add the `XDEBUG_SESSION=PHPSTORM` query parameter to the URL of the page you want to debug, or use [other available triggers ](https://xdebug.org/docs/step_debug#activate_debugger )
2021-06-23 10:36:31 +02:00
2022-10-05 10:46:47 +02:00
Alternatively, you can use [the **Xdebug extension** ](https://xdebug.org/docs/step_debug#browser-extensions ) for your preferred web browser.
3. On command line, we might need to tell PHPStorm which [path mapping configuration ](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging-cli.html#configure-path-mappings ) should be used, set the value of the PHP_IDE_CONFIG environment variable to `serverName=symfony` , where `symfony` is the name of the debug server configured higher.
Example:
```console
XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=symfony" php bin/console ...
```
2021-06-18 18:47:46 +02:00
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 ...
2022-10-05 10:46:47 +02:00
with Xdebug v3.x.x ...
2021-06-14 15:12:18 +02:00
```