Almost every Xdebug 3 guide I find online has the same two lines in it:
xdebug.mode = debug
xdebug.start_with_request = yes
start_with_request=yes tells Xdebug to start a debug session on every request and every CLI command. That
includes composer install, every artisan call, every test run and every asset request that hits PHP. With the IDE
closed, each one tries to connect first and logs a warning when it fails.
Xdebug always costs something while it is on: mode=debug alone made my tests about 50% slower. With the IDE
listening, start_with_request=yes piles on top of that, because every one of those sessions is real. That combination
is why people say Xdebug makes everything slow, and then turn it off and go back to var_dump() and dd().
Xdebug 3 already has a better default. With xdebug.mode=debug, the default value for start_with_request is
trigger, so a session starts only when the request carries a trigger. The IDE can listen all day, and only the
requests you ask to debug pay for a session. Add xdebug.mode=off for long test runs and benchmarks, and the rest of
the overhead goes too.
Where the cost comes from
Three separate things get blamed as “Xdebug is slow”:
start_with_request=yeswith the IDE listening. Every request and command opens a real debug session, and any breakpoint you left set stops it. With the IDE closed the connection is refused at once and costs almost nothing, unlessclient_hostdrops packets, when each process waits up toxdebug.connect_timeout_ms(200ms by default).- Modes.
debughooks into every function call, even with no session open.developreplacesvar_dump()and adds stack traces to errors.coverageandprofileinstrument every line or every call. - The extension being loaded. With
mode=off, Xdebug stays installed but does close to nothing.
Note
I timed the first cost on a Laravel app in Docker, with PhpStorm listening and no breakpoints hit:
mode=debug, PhpStorm listeningtriggeryes50 page loads, one at a time 3.71s 10.41s 50 page loads, 8 at once 0.80s 6.82s 52 Pest tests, 8 parallel workers 3.45s 7.74s Each session cost about 0.13s, and PhpStorm handled only a couple at a time, so parallel requests queued. For the second cost,
mode=debugalone made the tests about 50% slower thanmode=off,developdoubled that, andprofilemade them 8 times slower.
Triggers remove the first cost. The Docker section below shows how to remove the second with XDEBUG_MODE=off,
without rebuilding the image. That leaves only the third, which is close to zero.
The terminology trap
“Listening” means two different things in these guides:
- The IDE listens on port 9003 for incoming connections. This costs nothing. PhpStorm and VS Code can listen all day.
- Xdebug starts a session and connects out to the IDE. This is what
start_with_requestcontrols, and where the cost is.
So the setup is: the IDE listens whenever you like, and PHP only connects when a trigger asks it to.
How triggers work
Xdebug 3 looks for a trigger in these places:
XDEBUG_TRIGGERas a GET or POST parameter, a cookie, or an environment variable.XDEBUG_SESSIONas a cookie or an environment variable. Browser helper extensions set this cookie.XDEBUG_SESSION_STARTas a query parameter. Xdebug then sets theXDEBUG_SESSIONcookie, so later requests in that browser are debugged too, untilXDEBUG_SESSION_STOPclears it.
Any value works unless you set xdebug.trigger_value. ?XDEBUG_TRIGGER=1 is enough.
The ini file
This is the whole debug config for a Docker container:
; docker/php/xdebug.ini
xdebug.mode = debug
xdebug.start_with_request = trigger
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
; Uncomment while troubleshooting a connection, then comment it out again.
; xdebug.log=/tmp/xdebug.log
; xdebug.log_level=7
start_with_request=trigger is the default for mode=debug, so the line is optional. I keep it so the next person
reading the file knows it is deliberate.
client_port=9003 is the Xdebug 3 default. Xdebug 2 used 9000, which is also PHP-FPM’s port, so old guides and old IDE
configs cause confusion here.
Docker
The image
Install Xdebug behind a build argument so production images never include it:
ARG INSTALL_XDEBUG=false
RUN if [ "$INSTALL_XDEBUG" = "true" ]; then \
pecl install xdebug && docker-php-ext-enable xdebug \
&& printf '#!/bin/sh\nexec env XDEBUG_MODE=debug php -dxdebug.start_with_request=yes "$@"\n' > /usr/local/bin/phpd \
&& chmod +x /usr/local/bin/phpd; \
fi
The phpd script is the container version of my host alias. The CLI in Docker section further
down covers this.
Warning
Never ship Xdebug in a production image. One stray
XDEBUG_MODE=debugor leftover ini file turns triggers on, and then anyone who can add?XDEBUG_TRIGGER=1to a URL can start a debug session against whateverclient_hostpoints at. KeepINSTALL_XDEBUGdefaulting tofalse, so only the dev build ever installs it.
Compose
services:
app:
build:
context: ../../drafts
args:
INSTALL_XDEBUG: "true"
volumes:
- ./:/var/www/html
- ./docker/php/xdebug.ini:/usr/local/etc/php/conf.d/zz-xdebug.ini:ro
environment:
XDEBUG_MODE: "${XDEBUG_MODE:-debug}"
# (optional) handy to override xdebug settings from the env
XDEBUG_CONFIG: "${XDEBUG_CONFIG:-}"
# any name, as long as it matches a server under PHP > Servers in PhpStorm
PHP_IDE_CONFIG: "serverName=app"
extra_hosts:
- "host.docker.internal:host-gateway"
XDEBUG_MODEoverridesxdebug.modefrom the ini file.XDEBUG_MODE=off docker compose up -drecreates the container with Xdebug loaded but doing nothing, which removes the second cost from the list above and leaves only the third, which is close to zero. Use it for benchmarking or long test runs.XDEBUG_CONFIGoverrides other settings until the container is recreated, without touching the ini file. For example,XDEBUG_CONFIG="client_host=192.168.1.10" docker compose up -dpoints Xdebug at another machine. Separate settings with spaces: with commas, Xdebug reads the whole string as one invalid value and silently ignores it. PHP-FPM also ignoredstart_with_requestfromXDEBUG_CONFIGin my setup, so put that one in the ini file.PHP_IDE_CONFIGtells PhpStorm which server config to use for CLI sessions, since there is no host name to match on. VS Code ignores it.extra_hostsmakeshost.docker.internalresolve on Linux. Docker Desktop on macOS and Windows already provides it.
Mount the ini file instead of copying it in, so changing a setting needs only a container restart. No rebuild necessary.
Check it
docker compose exec app php -r 'xdebug_info();' | grep -E 'mode|start_with_request|client_host'
xdebug_info() in a browser gives the same report as HTML, including the last connection attempt.
PhpStorm
- Settings > PHP > Debug. Check the Xdebug debug port has
9003. Untick “Force break at first line when no path mapping specified” and “Force break at first line when a script is outside the project” if they get in your way. - Settings > PHP > Servers. Add a server named
app(or whatever name you gave it), matchingPHP_IDE_CONFIG. Set host and port to the URL you open in the browser, debugger to Xdebug, and tick “Use path mappings”. Map the project root to/var/www/html. - Click “Start Listening for PHP Debug Connections” (the bug icon in the toolbar to the left of run configurations, or Run > Start Listening for PHP Debug Connections). Leave it on.
The first triggered request without a matching server shows an “Incoming connection from Xdebug” dialogue. Accepting it creates the server entry for you, but you still need to fill in the path mapping.
VS Code
Install the PHP Debug extension, then add
.vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
Start “Listen for Xdebug” from the Run and Debug panel. VS Code does not use IDE keys or server names, so the path mapping is the only Docker-specific part.
Triggering a session
Browser
Install an Xdebug helper extension for your browser. It sets the XDEBUG_SESSION cookie when you click its icon and
removes it when you click again. The cookie value does not matter unless you set xdebug.trigger_value.
Without an extension, open any page with ?XDEBUG_SESSION_START=1 once. The cookie sticks until
?XDEBUG_SESSION_STOP=1.
CLI on the host
My shell has a phpd alias:
alias phpd="php -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003"
The host php.ini keeps xdebug.mode=off, so plain php, composer and test runs pay almost nothing. phpd artisan migrate or phpd vendor/bin/pest --filter=SomeTest turns the debugger on for that one command. Here
start_with_request=yes is fine, because it only applies to a command I chose to debug.
CLI in Docker
The container runs with mode=debug and start_with_request=trigger, so set the trigger as an environment variable:
docker compose exec -e XDEBUG_TRIGGER=1 app php artisan migrate
Or use the phpd script from the image:
docker compose exec app phpd artisan migrate
It is a script in /usr/local/bin, because docker compose exec runs the command without a shell. A shell alias
would never load there. The script sets XDEBUG_MODE=debug for its own process, because the XDEBUG_MODE environment
variable overrides any -dxdebug.mode flag. That keeps phpd working even when the container runs with
XDEBUG_MODE=off.
phpunit.xml cannot switch Xdebug off for test runs. xdebug.mode is fixed when PHP starts, so
<ini name="xdebug.mode"> does nothing, and <env name="XDEBUG_MODE"> reaches only the parallel workers, where it would
also switch off the debugger when you want it. Start the container with XDEBUG_MODE=off docker compose up -d for long
test runs instead. docker compose exec app phpd vendor/bin/pest --filter=SomeTest still debugs a single test, because
phpd sets its own mode. Browser and API triggers stay off until the container is recreated without it.
API clients
Add the trigger to the query string:
POST https://app.test/api/orders?XDEBUG_TRIGGER=1
Content-Type: application/json
The body stays untouched, so this works for JSON, form data and file uploads. In Postman, Insomnia, Bruno or
PhpStorm’s HTTP client, add XDEBUG_TRIGGER as a query parameter on the request or on a collection-level variable.
A Cookie: XDEBUG_SESSION=1 header works too.
When it does not connect
- Run
xdebug_info()and check the mode isdebugand the client host is right. - Uncomment
xdebug.logand retry. The log says whether a trigger was found and which host and port it tried. - “Trigger value not found” means the request did not carry a trigger. Check the cookie or query string.
- “Could not connect to debugging client” means the IDE is not listening, the port is wrong, or
client_hostdoes not resolve from inside the container. - A session that connects but never stops on a breakpoint is almost always a wrong path mapping.