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 https://github.com/dunglas/symfony-docker/commit/330ea245a1e0cb7390adde68167b922d393ba25a 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 https://github.com/dunglas/frankenphp/issues/1504

[henryfoster]

Having the same issue with PHPStorm 2025.1.3

It works when removing the worker config in the Caddyfile as mentioned by @7-zete-7 here https://github.com/dunglas/symfony-docker/issues/782#issuecomment-2798734473

Maybe a hint in the docs would be nice if it's currently not possible to fix?

[rvanlaak]

With the latest version (did a build this morning) of frankenphp I'm having issues with variable data not being shown. The request does trigger an incoming connection.

xdebug.mode=debug

;xdebug.client_host = xdebug://gateway
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

Can not get xdebug.client_host = xdebug://gateway to work in any way too.

[tehmaestro]

Hey, wanted to confirm that xdebug does not work in worker-mode, it only works in normal mode (had to edit the Caddyfile) PHPStorm: 2025.1.1 PHP: 8.4.11 XDebug: 3.4.5

xdebug_connect_to_client also hangs the request

[imper86]

Cand confirm the same issue on PHPStorm 2025.2.1, PHP 8.4.12, XDebug 3.4.5 :( Disabling worker mode helps

For now I use this in my Makefile:

up-xdebug: ## Start docker hub with xdebug enabled
	sed -i '' '/^[[:space:]]\{2\}worker {/,/^[[:space:]]\{2\}}/d' frankenphp/Caddyfile && XDEBUG_MODE=debug docker compose up --force-recreate && git checkout frankenphp/Caddyfile

[korkhau]

For everyone who use limactl on macOS and do not see Xdebug working even after worker directive was removed.

It seems that host.docker.internal is available only on Docker Desktop and not for Lima/Colima. And we need to fix it:

1. Go to your lima instance shell e.g. limactl shell default
2. Retrive VM's IP via ip route | grep default
3. Add this IP to 20-app.dev.ini:

;xdebug.client_host = host.docker.internal
xdebug.client_host = <ip here>

4. Run docker compose XDEBUG_MODE=debug docker compose up --force-recreate

At first run PHPStorm will prompt you with mapping configuration, just accept it or manually add "Server" configuration:

Now Xdebug is working on MacOS with Lima + Docker + FrankenPHP

[genesisbertiz]

I had the same issue with Xdebug not triggering. I fixed it by adding this to 20-app.dev.ini:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

Make sure to restart the container after changing it. The first request might not trigger Xdebug, so try twice if needed, worked for me.

[comONCreation]

Hello,

With the current dunglas/symfony-docker (FrankenPHP + Caddy) on macOS (OrbStack), I can’t get PhpStorm to auto-attach to Xdebug via “Listen for PHP Debug Connections.”

I either get an “Incoming Connection” dialog without Server Name and with Server port = 80 (even though I’m using HTTPS), and it never attaches — or I must manually start a PHP Remote Debug configuration (filtered by IDE key) to force it. When using the Remote Debug config, breakpoints only trigger on the second browser refresh, and the connection is unstable.

This feels like a mismatch between the Docker image’s Xdebug configuration, FrankenPHP workers, and PhpStorm’s DBGp server association.

---

Environment

• macOS (Intel MBP 16" 2019) with OrbStack
• Symfony Docker template (FrankenPHP + Caddy)
• PHP 8.4.13, Xdebug 3.x
• PhpStorm (latest, port 9003, “Listen for PHP Debug Connections” enabled)
• Project URL: https://localhost/ (443)
• Mapping in PhpStorm: local project → /app

---

Expected behavior

With PhpStorm listening, visiting https://localhost/ should automatically attach Xdebug and hit breakpoints — no need to manually start a “PHP Remote Debug” run configuration.

---

Actual behavior

1. If I disable “Ignore external connections through unregistered servers” in PhpStorm: I get an Incoming Connection dialog with:

   • Empty Server name
   • Server port = 80 (while browsing on 443/HTTPS) Even after accepting and mapping manually, the connection doesn’t attach reliably.

2. If I enable “Ignore external connections…” and start a PHP Remote Debug run config:

   • Xdebug connects, but breakpoints are hit only after the second page refresh.
   • Connection stability varies randomly.

---

Xdebug configuration (forced via .ini, not ENV)

frankenphp/conf.d/20-app.dev.ini:

xdebug.mode = develop,debug
xdebug.start_with_request = yes
xdebug.discover_client_host = 0
xdebug.client_host = host.docker.internal   ; resolves to 0.250.250.254 on OrbStack
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 7
zend.exception_ignore_args = Off

---

docker-compose.override.yml (relevant part)

services:
  php:
    build:
      context: .
      target: frankenphp_dev
    volumes:
      - ./:/app
      - ./frankenphp/Caddyfile:/etc/frankenphp/Caddyfile:ro
      - ./frankenphp/conf.d/20-app.dev.ini:/usr/local/etc/php/app.conf.d/20-app.dev.ini:ro
    environment:
      APP_ENV: dev
      # Tried this as well:
      # PHP_IDE_CONFIG: "serverName=symfony"
      # XDEBUG_MODE: "${XDEBUG_MODE:-off}"  <-- Has **no effect at all**
    extra_hosts:
      - host.docker.internal:host-gateway

⚠️ Note: The XDEBUG_MODE environment variable doesn’t seem to be picked up at all — even when explicitly set in docker-compose.override.yml. This is why I had to force the Xdebug mode directly in .ini, otherwise it always stays on “develop” (as defined in docker-php-ext-xdebug.ini).

---

PhpStorm configuration

Servers:

• Name: symfony
• Host: localhost
• Port: 443
• Use HTTPS checked
• Path mappings: project root → /app

Run Config (manual workaround):

• “PHP Remote Debug” with:

  • Server: symfony
  • IDE key: PHPSTORM
  • “Filter debug connection by IDE key” checked

---

What I already tried

• Forcing Xdebug settings via .ini (since XDEBUG_MODE ENV doesn’t apply).

• Setting discover_client_host=0 and client_host=host.docker.internal.

• Verified DNS: getent hosts host.docker.internal → 0.250.250.254.

• PhpStorm listening on 9003 (lsof -nP -iTCP:9003 -sTCP:LISTEN shows PhpStorm).

• Toggled PhpStorm debug options:

  • Filter by IDE key (on/off)
  • Ignore unregistered servers (on/off)

• Added PHP_IDE_CONFIG=serverName=symfony (and matched PhpStorm server name).

• Tried plain HTTP (port 80) instead of HTTPS (443).

• Hardcoded xdebug.client_host = 0.250.250.254.

Result: Same issue — either unstable or doesn’t attach at all. /tmp/xdebug.log shows connections like:

[Step Debug] Connecting to configured address: host.docker.internal:9003.

but PhpStorm either:

• Pops up an “Incoming Connection” window with empty server name and port 80, or
• Only hits breakpoints on the second refresh when running a PHP Remote Debug config.

---

Questions / possible causes

• Could FrankenPHP’s worker model or Caddy reverse proxy interfere with how PhpStorm interprets incoming DBGp connections (missing server name / wrong port)?
• Should the template include an .ini under /usr/local/etc/php/conf.d (not app.conf.d) to override docker-php-ext-xdebug.ini cleanly?
• Is HTTPS behind Caddy making PhpStorm think the request originates from port 80 instead of 443?
• Any known reason XDEBUG_MODE in environment: would be ignored by the PHP process inside the container?
• Any recommended approach for propagating PHP_IDE_CONFIG reliably to FrankenPHP workers for PhpStorm auto-association (without needing a “PHP Remote Debug” config)?

---

Thanks! Happy to test changes, collect more logs, or run experimental images if it helps isolate this behavior.

[dunglas]

This is a known xdebug issue. We'll have to observe xdebug with strace and similar tools to understand what's going on.

In the meantime a workaround is to disable the worker mode.