All posts

Xdebug 3 on demand: debug sessions only when you ask for one

Setting up Xdebug 3 with triggers for the browser, CLI and API clients, in Docker, with PhpStorm and VS Code.

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”:

  1. start_with_request=yes with 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, unless client_host drops packets, when each process waits up to xdebug.connect_timeout_ms (200ms by default).
  2. Modes. debug hooks into every function call, even with no session open. develop replaces var_dump() and adds stack traces to errors. coverage and profile instrument every line or every call.
  3. 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 listening trigger yes
50 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=debug alone made the tests about 50% slower than mode=off, develop doubled that, and profile made 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_request controls, 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_TRIGGER as a GET or POST parameter, a cookie, or an environment variable.
  • XDEBUG_SESSION as a cookie or an environment variable. Browser helper extensions set this cookie.
  • XDEBUG_SESSION_START as a query parameter. Xdebug then sets the XDEBUG_SESSION cookie, so later requests in that browser are debugged too, until XDEBUG_SESSION_STOP clears 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=debug or leftover ini file turns triggers on, and then anyone who can add ?XDEBUG_TRIGGER=1 to a URL can start a debug session against whatever client_host points at. Keep INSTALL_XDEBUG defaulting to false, 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_MODE overrides xdebug.mode from the ini file. XDEBUG_MODE=off docker compose up -d recreates 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_CONFIG overrides 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 -d points 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 ignored start_with_request from XDEBUG_CONFIG in my setup, so put that one in the ini file.
  • PHP_IDE_CONFIG tells PhpStorm which server config to use for CLI sessions, since there is no host name to match on. VS Code ignores it.
  • extra_hosts makes host.docker.internal resolve 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

  1. 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.
  2. Settings > PHP > Servers. Add a server named app (or whatever name you gave it), matching PHP_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.
  3. 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

  1. Run xdebug_info() and check the mode is debug and the client host is right.
  2. Uncomment xdebug.log and retry. The log says whether a trigger was found and which host and port it tried.
  3. “Trigger value not found” means the request did not carry a trigger. Check the cookie or query string.
  4. “Could not connect to debugging client” means the IDE is not listening, the port is wrong, or client_host does not resolve from inside the container.
  5. A session that connects but never stops on a breakpoint is almost always a wrong path mapping.

Comments