XDebug not working with PhpStorm

[danut007ro]

Hello,

I'm trying to use XDebug with PhpStorm on a fresh clone of this repo. I followed all the steps outlined in the documentation. Here are my relevant settings in PhpStorm:

I added the following lines in 20-app.dev.ini:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.log=/tmp/xdebug.log
xdebug.log_level=10

I'm using XDEBUG_MODE=debug docker compose up --build command to start the project, but PhpStorm shows an error popup (screenshot below).

Cannot accept external Xdebug connection
Cannot evaluate expression '$_SERVER['SERVER_PORT']'

The log in /tmp/xdebug.log shows that indeed XDebug is connecting to PhpStorm but it's another issue, here's part of the log:

root@530aecc4a80a:/app# cat /tmp/xdebug.log 
[281473732758880] Log opened at 2025-04-11 16:01:50.121074
[281473732758880] [Config] WARN: Not setting up control socket with default value due to unavailable 'tsc' clock
[281473732758880] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:9003.
[281473732758880] [Step Debug] INFO: Connected to debugging client: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port).
[281473732758880] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///app/bin/console" language="PHP" xdebug:language_version="8.3.19" protocol_version="1.0" appid="281473732758880"><engine version="3.4.2"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2025 by Derick Rethans]]></copyright></init>

[281473732758880] [Step Debug] <- feature_set -i 1 -n show_hidden -v 1
[281473732758880] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="show_hidden" success="1"></response>
...

Did I miss something about the setup? Thanks!

[7-zete-7]

Hi @danut007ro!

Thanks for the detailed information about the problem.

I was able to reproduce the described problem.

Used versions:
FrankenPHP v1.5.0
PHP 8.3.19
Xdebug v3.4.2
PhpStorm 2024.3.5

The difference was connecting Xdebug via Unix Domain Socket instead of host.docker.internal:9003. This did not affect the problem.

The $_SERVER['SERVER_PORT'] error is observed both in worker mode and without it.

Xdebug starts working correctly when worker mode is disabled.

The problem is also observed on FrankenPHP v1.4.4.

The problem is also observed on Xdebug v3.3.1.

I can't downgrade PhpStorm yet.

@danut007ro, What version of PhpStorm are you using? Сan you check if the problem will reoccur when downgrading PhpStorm?

[danut007ro]

@7-zete-7 thanks for looking into this.

My versions are:
FrankenPHP 1.5.0 (with Caddy 2.9.1)
PHP 8.3.20
XDebug 3.4.2
PhpStorm 2024.3.5

I tried downgrading to PhpStorm 2023.1.6 and also added PHP_IDE_CONFIG: "serverName=medradar" in compose.override.yaml to match the defined server in PhpStorm configuration.

I was unable to use XDebug with any of the attempts above.

Thank you.

[maciejlewandowskii]

I tested other PhpStorm versions and could reproduce on 2024.3.5, 2024.3.4, 2023.1.6, and the newest EAP.
The behavior was the same: not working on any trigger (besides manually adding xdebug_break(); or using start_with_request=yes). Has anyone tested if VScode is behaving the same way?

[7-zete-7]

@danut007ro, Try to disable worker mode in FrankenPHP, it should help. You can disable worker mode by making the following chanes to Caddyfile:

 	# ...
 	frankenphp {
 		{$FRANKENPHP_CONFIG}
 
-		worker {
-			file ./public/index.php
-			env APP_RUNTIME Runtime\FrankenPhpSymfony\Runtime
-			{$FRANKENPHP_WORKER_CONFIG}
-		}
 	}
 	# ...

This is currently the actual solution for problems with Xdebug and FrankenPHP.

I checked and it actually solves the problem for your configuration.

Know several ways to make Xdebug work in worker mode. However, I can't recommend any of the methods I know, because each of them has problems for now.

[danut007ro]

@7-zete-7, Removing the config from Caddyfile works indeed. This will remove it from prod env also, right?

@dunglas added workers in dev (watch) in 330ea24 so maybe that can be improved somehow?

Thank you.

[7-zete-7]

@danut007ro, you are right. This change also will disable workers for prod.

If you plan to use Xdebug a frequently in dev, you should probably revert #770 and #765 for your project for now.

[maxhelias]

We need to improve the documentation on how to use xdebug with worker mode. This is a concern linked to the management of the PID (process ID) and the lifecycle of the PHP process. Xdebug has a new feature to get around this problem in this case see at this time code : https://youtu.be/gOH1ElakyLw?t=1314

[7-zete-7]

@maxhelias, I also thought about using the xdebug_connect_to_client() function (adding its call in the App\Kernel::handle() method). But at the moment it just hangs FrankenPHP for me.

For now, the solution for me is to use the function xdebug_break() (also in the App\Kernel::handle() method). When this function is called, PHP connects to the IDE and debugging starts working. But there is always a forced break in execution.

 # ...
 class Kernel extends BaseKernel
 {
     # ...
+    public function handle(Request $request, int $type = HttpKernelInterface::MAIN_REQUEST, bool $catch = true): Response
+    {
!        extension_loaded('xdebug') && xdebug_break();
+
+        return parent::handle($request, $type, $catch);
+    }
     # ...
 }

Perhaps there is a more correct place to call the function xdebug_connect_to_client() so that it does not lead to a hang.

Reported issue php/frankenphp#1504