XDebug breakpoint and worker mode

[xavierleune]

Hi there,

Sorry if it's a silly question. I've been trying to use a debug session with my IDE and frankenphp running in worker mode. The only way I got it working was to use the function xdebug_break.
Without it, when I start the worker and try to use a breakpoint with my IDE, I got a path missmatch between the container and the IDE (even if it's configured as it should).
Maybe it's a limitation of franken. In this case it's totally fine but I'll propose an entry in the documentation about it. Or maybe I'm just dumb 'cause you got it working and I just have to doubledecuple check ?
No big deal but it's been scratching my mind for a few days.

Thanks !

[dunglas]

Xdebug not working in worker mode is a known issue. I didn't find the time to investigate it, but it's on my todo list.

Any help welcome!

[xavierleune]

Ok thanks, actually I got it working but it requires a manual xdebug_break in the code. So if you want I can write a small guide for the documentation about it.

[henderkes]

We should look into getting xdebug_connect_to_client to work instead.

[henderkes]

I can debug with xdebug in worker mode just fine.

Settings:

15-xdebug.ini

[xdebug]
zend_extension=xdebug-zts-85

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.ide_key="phpstorm"

Caddyfile:

{$SERVER_NAME:http://} {
    root ./public
    log
    encode zstd br gzip
    php_server {
        root ./public
        worker index.php 1
    }
}

Runner (SymfonyRuntime 8.0):

        $handler = function () use ($server, &$sfRequest, &$sfResponse): void {
            // Connect to the Xdebug client if it's available
            if (\extension_loaded('xdebug') && \function_exists('xdebug_connect_to_client')) {
                xdebug_connect_to_client();
            }

            // Merge the environment variables coming from DotEnv with the ones tied to the current request
            $_SERVER += $server;

            $sfRequest = Request::createFromGlobals();
            $sfResponse = $this->kernel->handle($sfRequest);

            $sfResponse->send();
        };

        $loops = 0;
        do {
            $ret = frankenphp_handle_request($handler);

            if ($this->kernel instanceof TerminableInterface && $sfRequest && $sfResponse) {
                $this->kernel->terminate($sfRequest, $sfResponse);
            }

            gc_collect_cycles();
        } while ($ret && (0 >= $this->loopMax || ++$loops < $this->loopMax));

php -v:

❯❯ symfony-demo git:(main) 21:27 php-zts -v
PHP 8.5.2 (cli) (built: Jan 16 2026 01:36:34) (ZTS zig 0.15.2 x86_64)
Copyright (c) The PHP Group
Built by Static PHP <https://static-php.dev> #StandWithUkraine
Zend Engine v4.5.2, Copyright (c) Zend Technologies
    with Xdebug v3.5.1, Copyright (c) 2002-2026, by Derick Rethans
    with Zend OPcache v8.5.2, Copyright (c), by Zend Technologies

[xavierleune]

Good to know ! Thanks for sharing! Maybe we can try to add xdebug to MODULES_TO_RELOAD, if it works without the connect thing, we may propose a PR on xdebug to hook on sapi.activate ? Or something like that?

[xavierleune]

I gave it a shot: xdebug/xdebug#1063