bachir/docker-materio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Xdebug: off by default on CLI, auto-triggered on web only

Browse Source 
Loading xdebug.mode=debug at all times made every drush/composer command
noticeably slower, since Xdebug hooks every function call as soon as the
mode is active regardless of whether a debugger connects. Split the config
per-SAPI instead: CLI defaults to xdebug.mode=off (opt in with the new
xdebugon/xdebugoff aliases or XDEBUG_MODE=debug XDEBUG_TRIGGER=1), while
php-fpm keeps xdebug.mode=debug + start_with_request=yes so browser
requests still auto-connect with no trigger needed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
bachir
2026-09-21 14:09:05 +02:00
co-authored by Claude Sonnet 5
parent 0a45ff2d10
commit 8040225ace
2 changed files with 37 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+24
View File
@@ -90,6 +90,30 @@ sudo docker exec -it materiod8_php_1 bash
```
once inside the php container in /var/www/html you can use drush as usual
### Xdebug
Xdebug is installed in the php container, listening for your IDE on `host.docker.internal:9001` (see `ressources/xdebug.ini`, `.vscode/launch.json` in `public_html`).
Web and CLI behave differently on purpose, because leaving `xdebug.mode=debug` on all the time makes every `drush`/`composer` command noticeably slower (Xdebug hooks every function call as soon as the mode is active, whether or not a debugger actually connects):
- **Browser requests (php-fpm)**: Xdebug is always on (`xdebug.mode=debug`, `xdebug.start_with_request=yes`). Just start listening in your IDE and load the page, no trigger needed.
- **CLI (`drush`, `composer`, ...)**: Xdebug is **off by default** (`xdebug.mode=off`) so commands stay fast. To debug a specific command, turn it on for the current shell first:
```
xdebugon
drush some:command
xdebugoff
```
`xdebugon`/`xdebugoff` are shell aliases defined in `/etc/bash.bashrc` inside the php container (they set/unset `XDEBUG_MODE=debug` and `XDEBUG_TRIGGER=1`). You can also do it inline for a single command:
```
XDEBUG_MODE=debug XDEBUG_TRIGGER=1 drush some:command
```
This split is implemented as two extra ini files loaded per-SAPI, see `Docker/php/Dockerfile`:
- `/usr/local/etc/php/conf.d/zz-xdebug-cli.ini` → loaded by both CLI and php-fpm (default conf.d), sets `xdebug.mode=off`.
- `/usr/local/etc/php/fpm-conf.d/zz-xdebug-fpm.ini` → only loaded by php-fpm (via `PHP_INI_SCAN_DIR` in `/start.sh`), overrides back to `xdebug.mode=debug` for web requests.
If you change any of these files, rebuild the php image (`make buildphp`) and recreate the container (`make up`) — do not use raw `docker-compose up`, it won't pick up `USER_UID`/`USER_GID` and the container will run as root (see Makefile section below).
### gulp
Dev process needs gulp to run in:
- public_html/sites/all/modules/custom/materio/