Update XDebug documentation to recommend discover_client_host=yes.

docker/docker-compose.development.yml

@@ -21,8 +21,8 @@ services:
       - '80:80'
     environment:
       XDEBUG_MODE: debug
-      XDEBUG_CONFIG: client_host=172.17.0.1
-      # Enable these for PHPStorm:
+      XDEBUG_CONFIG: discover_client_host=yes
+      # Enable this for PHPStorm:
       #XDEBUG_SESSION: PHPSTORM
       #PHP_IDE_CONFIG: serverName=localhost
 

docs/development/environment/debug.md

@@ -3,42 +3,49 @@
 The farmOS development Docker image comes pre-installed with
 [XDebug](https://xdebug.org) 3, which allows debugger connections on port 9003.
 
-In order to connect to it, the `XDEBUG_CONFIG` environment variable must be
-used to configure XDebug's `client_host` setting  with the Docker container's
-"Gateway" IP address.
+XDebug can be configured to discover the client host automatically with the
+following environment variables in `docker-compose.yml`:
+
+    environment:
+      XDEBUG_MODE: debug
+      XDEBUG_CONFIG: discover_client_host=yes
+
+## PHPStorm
+
+If you are using the PHPStorm IDE, an additional `XDEBUG_SESSION: PHPSTORM`
+environment variable is necessary.
+
+For example:
+
+    environment:
+      XDEBUG_MODE: debug
+      XDEBUG_CONFIG: discover_client_host=yes
+      XDEBUG_SESSION: PHPSTORM
+
+With this configuration in place, enable the "Start listening for PHP Debug
+Connections" option. Add a breakpoint in your code, load the page in your
+browser, and you should see a prompt appear in PHPStorm that will begin the
+debugging session and pause execution at your breakpoint.
+
+### Drush + PHPStorm
+
+Debugging code that is run via [Drush](/development/environment/drush) commands
+requires additional configuration.
+
+The `discover_client_host=yes` configuration used above will not work when code
+is executed via the command line. The Docker host IP must be set explicitly.
 
 With the containers running, this command will print the gateway IP:
 
     docker inspect farmos_www_1 | grep -o '"Gateway": ".*\..*\..*\..*"'
 
-Edit `docker-compose.yml` and enter the gateway IP in the `XDEBUG_CONFIG`
-environment variable. For example:
+Edit `docker-compose.yml` and set the `client_host` setting in the `XDEBUG_CONFIG`
+environment variable to the gateway IP.
 
-    environment:
-      XDEBUG_MODE: debug
-      XDEBUG_CONFIG: client_host=192.168.128.1
+It is also necessary to add a `PHP_IDE_CONFIG` environment variable with a
+value of `serverName=localhost`.
 
-Restart the Docker containers for this change to take affect.
-
-    docker-compose restart
-
-**Note**: If the Docker containers are removed and recreated, the IP address
-may change, and you will need to repeat these steps to reconfigure it.
-
-## PHPStorm
-
-If you are using the PHPStorm IDE, with the configuration above in place,
-enable the "Start listening for PHP Debug Connections" option. Add a
-breakpoint in your code, load the page in your browser, and you should see
-a prompt appear in PHPStorm that will begin the debugging session and pause
-execution at your breakpoint.
-
-### Drush + PHPStorm
-
-Debugging code that is run via [Drush](/development/environment/drush) commands
-requires additional configuration. Add an `XDEBUG_SESSION` environment variable
-with a value of `PHPSTORM`, and a `PHP_IDE_CONFIG` environment variable with a
-value of `serverName=localhost`, as follows:
+For example:
 
     environment:
       XDEBUG_MODE: debug