init

2026-06-11 21:44:19 +02:00
commit d36bce3e86
57 changed files with 8164 additions and 0 deletions
@@ -0,0 +1,98 @@
+# Using Xdebug
+
+The default development image is shipped with [Xdebug](https://xdebug.org/),
+a popular debugger and profiler for PHP.
+
+When using [Dev Containers](https://containers.dev/), 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:
+
+```console
+XDEBUG_MODE=develop,debug docker compose up --wait
+```
+
+On Windows:
+
+```console
+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](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html):
+
+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](https://xdebug.org/docs/step_debug#activate_debugger)
+
+   Alternatively, you can use [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions)
+   for your preferred web browser.
+
+3. On the 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
+   above.
+
+   Example:
+
+   ```console
+   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](https://marketplace.visualstudio.com/items?itemName=DEVSENSE.phptools-vscode).
+2. Add [debug configuration](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launch-configurations)
+   into your `.vscode\launch.json` file.
+
+   Example:
+
+   ```json
+   {
+     "version": "0.2.0",
+     "configurations": [
+       {
+         "name": "Debug PHP",
+         "type": "php",
+         "request": "launch",
+         "pathMappings": {
+           "/app": "${workspaceFolder}"
+         }
+       }
+     ]
+   }
+   ```
+
+3. Use [Run and Debug](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session)
+   options and run `Debug PHP` to listen for upcoming connections
+   with [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions)
+   installed and active.
+
+## Troubleshooting
+
+Inspect the installation with the following command.
+The Xdebug version should be displayed.
+
+```console
+$ docker compose exec php php --version
+
+PHP ...
+    with Xdebug v3.x.x ...
+```