Start Xdebug only for the request you want

1. Turn the proxy on

The proxy is off by default. Add MCP_ENABLED=true too if you want an AI assistant to read the session; otherwise the first line is enough.

XDEBUG_PROXY_ENABLED=true
MCP_ENABLED=true

If your IDE also listens on port 9003, move the IDE to 9004 (PhpStorm: Settings → PHP → Debug → Xdebug → Debug port). The proxy passes the session on to it.

2. Set the trigger in php.ini

A typical php.ini for Buggregator. The last line is the one that limits debugging to triggered requests.

xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=trigger

3. In Docker, open the proxy to the network

By default the proxy listens on 127.0.0.1:9003 inside its container, so PHP in another container cannot reach it. When PHP and Buggregator both run in Compose, make the proxy listen on all interfaces and dial the IDE on your machine:

    environment:
      XDEBUG_PROXY_ENABLED: "true"
      XDEBUG_PROXY_ADDR: 0.0.0.0:9003
      XDEBUG_PROXY_IDE_ADDR: host.docker.internal:9003
    extra_hosts:
      - host.docker.internal:host-gateway   # needed on Linux

Then set xdebug.client_host to the Buggregator service name, for example buggregator. Here the IDE can stay on port 9003. PHP on your machine needs a different layout; see the Docker section of the Xdebug docs.

4. Send the trigger

Add XDEBUG_TRIGGER to the one request you want to debug: as a GET or POST variable, or as a cookie. For a CLI script, set the XDEBUG_TRIGGER environment variable. Xdebug does not look at the value, unless you set xdebug.trigger_value; then only a matching value starts it.

5. Tell the script where to stop

Without an IDE, put this line where you want to stop, or set a breakpoint on the Xdebug page.

xdebug_break();

In trigger mode, Xdebug's docs say xdebug_break() also starts a session on its own.

The trigger rules are Xdebug's own: in trigger mode it checks for XDEBUG_TRIGGER in $_ENV, $_GET, $_POST and $_COOKIE when the request starts (https://xdebug.org/docs/all_settings#start_with_request). A triggered request connects to Buggregator on port 9003. Buggregator passes it to your IDE or, with no IDE, drives it from the Xdebug page.