Using Xdebug #

The default development image is shipped with Xdebug, a popular debugger and profiler for PHP.

When using Dev Containers, Xdebug is pre-configured and works out of the box. Open the Run and Debug panel in Visual Studio Code and start the Debug PHP launch configuration, then set your breakpoints and load a page.

For other setups, because it has a significant performance overhead, the step-by-step debugger is disabled by default. It can be enabled by including debug in the values of the XDEBUG_MODE environment variable.

On Linux and Mac:

XDEBUG_MODE=develop,debug docker compose up --wait

On Windows:

set XDEBUG_MODE=develop,debug&& docker compose up --wait&set XDEBUG_MODE=

Debugging with Xdebug and PhpStorm #

First, create a PHP debug remote server configuration:

1. In the Settings/Preferences dialog, go to PHP | Servers
2. Create a new server:
   • Name: symfony (or whatever you want to use for the variable PHP_IDE_CONFIG)
   • Host: localhost (or the one defined using the SERVER_NAME environment variable)
   • Port: 443
   • Debugger: Xdebug
   • Check Use path mappings
   • Absolute path on the server: /app

You can now use the debugger!

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

   Alternatively, you can use the Xdebug extension for your preferred web browser.

3. On the command line, we might need to tell PhpStorm which path mapping configuration 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 above.

   Example:

   XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=symfony" php bin/console ...
   

Debugging with Xdebug and Visual Studio Code #

1. Install necessary PHP extension for Visual Studio Code.

2. Add debug configuration into your .vscode\launch.json file.

   Example:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Debug PHP",
         "type": "php",
         "request": "launch",
         "pathMappings": {
           "/app": "${workspaceFolder}"
         }
       }
     ]
   }
   

3. Use Run and Debug options and run Debug PHP to listen for upcoming connections with the Xdebug extension installed and active.

Troubleshooting #

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

$ docker compose exec php php --version

PHP ...
    with Xdebug v3.x.x ...