Add Docker Xdebug troubleshooting

environments/docker/general.md

@@ -52,3 +52,93 @@ volumes:
   - ../:/home/invoiceshelf/app
   - ./php/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
 ```
+
+# Troubleshooting
+
+Use the checks below when Xdebug is installed but the IDE does not stop at breakpoints.
+
+## Confirm Xdebug is Loaded
+Run this inside the PHP container:
+
+```bash
+php -v
+php -m | grep xdebug
+php --ri xdebug
+```
+
+If Xdebug is missing, rebuild the image so the `pecl install xdebug` and `docker-php-ext-enable xdebug` steps run again:
+
+```bash
+docker compose build --no-cache
+docker compose up -d
+```
+
+## Use the Correct Host Address
+`xdebug.client_host=172.17.0.1` works for many Linux Docker installs, but it is not universal.
+
+For Docker Desktop on macOS or Windows, use:
+
+```ini
+xdebug.client_host=host.docker.internal
+```
+
+For native Linux Docker, confirm the bridge gateway from the container:
+
+```bash
+ip route | awk '/default/ { print $3 }'
+```
+
+Use the printed IP as `xdebug.client_host`.
+
+## Match the IDE Port
+Xdebug 3 commonly uses port `9003`, while older examples often use `9000`. Make sure the port in `xdebug.ini` matches the port your IDE listens on:
+
+```ini
+xdebug.client_port=9003
+```
+
+If you keep `9000`, update the IDE debug port to `9000` as well.
+
+## Check the Xdebug Log
+The example config writes logs to `/var/log/xdebug.log`. If the file is empty or missing, the PHP process may not be able to write there.
+
+Create a writable log path inside the container:
+
+```bash
+touch /tmp/xdebug.log
+chmod 666 /tmp/xdebug.log
+```
+
+Then update the config:
+
+```ini
+xdebug.log=/tmp/xdebug.log
+xdebug.log_level=7
+```
+
+Reload the container and inspect the log after making a request:
+
+```bash
+docker compose restart
+docker compose exec app tail -f /tmp/xdebug.log
+```
+
+Replace `app` with the name of your PHP service.
+
+## Verify the Config File is Mounted
+If you mount `xdebug.ini` as a volume, confirm Docker is reading the file you edited:
+
+```bash
+docker compose exec app cat /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
+```
+
+If the output is stale, restart the container. If the file is missing, check the relative path in the `volumes` entry.
+
+## Debugging CLI Commands and Tests
+For CLI debugging, pass the IDE server name and enable debug mode for the command:
+
+```bash
+PHP_IDE_CONFIG="serverName=invoiceshelf.test" XDEBUG_MODE=debug php artisan test
+```
+
+The `serverName` value must match the server configured in your IDE, and the local project path must map to the path inside the container.