From fcff96b69136c0acf731084cb64d32ad32b92733 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= <kevin@dunglas.fr>
Date: Wed, 22 Dec 2021 12:06:26 +0100
Subject: [PATCH] docs(xdebug): fix host on Linux
---
docs/xdebug.md | 34 +++++++++++++++++++---------------
1 file changed, 19 insertions(+), 15 deletions(-)
diff --git a/docs/xdebug.md b/docs/xdebug.md
index 5dd9522..1a6ea89 100644
--- a/docs/xdebug.md
+++ b/docs/xdebug.md
@@ -1,7 +1,8 @@
# Installing Xdebug
-The default Docker stack is shipped without a Xdebug stage.
-It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
+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.
## Add a Debug Stage to the Dockerfile
@@ -12,7 +13,7 @@ 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.0.4
+ARG XDEBUG_VERSION=3.1.2
RUN set -eux; \
apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
pecl install xdebug-$XDEBUG_VERSION; \
@@ -25,7 +26,7 @@ RUN set -eux; \
Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yml` ensures that the production
configuration remains untouched.
-As example, an override could look like this:
+As an example, an override could look like this:
```yaml
# docker-compose.debug.yml
@@ -47,9 +48,12 @@ services:
# 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:
+Build your image with your fresh new XDebug configuration:
```console
docker-compose -f docker-compose.yml -f docker-compose.debug.yml build
@@ -65,29 +69,29 @@ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
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).
-If you don't want to use it, just add on your request this query param: `XDEBUG_SESSION=PHPSTORM`.
+If you don't want to use it, add on your request this query param: `XDEBUG_SESSION=PHPSTORM`.
-On PHPStorm, you just have to click on the button `Start Listening for PHP Debug Connections` on the `Run` menu.
+On PHPStorm, click on `Start Listening for PHP Debug Connections` in the `Run` menu.
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:
- * 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**
+ * 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 requested Xdebug version should be displayed in the output.
+Inspect the installation with the following command. The Xdebug version should be displayed.
```console
$ docker-compose exec php php --version
PHP ...
- with Xdebug v3.0.4 ...
+ with Xdebug v3.1.2 ...
```