In always-on debug mode (start_with_request=yes, the default), every PHP
invocation attempts to connect to the IDE debugger and logs an error when
nothing is listening. This pollutes terminal output during normal development.
Switch to trigger mode so XDebug only initiates a debug session when
explicitly requested:
- CLI: prefix commands with XDEBUG_TRIGGER=1
- Web: set the XDEBUG_TRIGGER cookie or query parameter (use the Xdebug
Helper browser extension for convenience)
Also remove XDEBUG_TRIGGER=yes from the env file. That line set the trigger
env var unconditionally, which would have caused XDebug to always fire even
in trigger mode.
XDebug defaults client_host to 'localhost', which inside a Docker container
resolves to the container itself rather than the host machine where the IDE
debugger is listening. This causes every PHP invocation to fail with
'Could not connect to debugging client. Tried: localhost:9003'.
Add extra_hosts to the php service so that host.docker.internal resolves to
the Docker host IP via host-gateway. This works on all platforms (Docker
Desktop on macOS/Windows, native Linux Docker, WSL2).
Set XDEBUG_CONFIG=client_host=host.docker.internal in the xdebug env file so
XDebug connects to the host machine instead of the container.
Also remove the now-stale commented port binding (9000:9000 from XDebug 2).
XDebug 3 makes outbound connections from the container to the IDE — no port
publishing is needed or appropriate.
This change should ease the spawn of a development environment.
It can be used as a vscode devcontainer.
Signed-off-by: Kevin Decherf <kevin@kdecherf.com>
Yassine Guedidi
Kevin Decherf