Trouble Configuring Xdebug in Official FrankenPHP Docker Image

[adelynx]

Description:

Hello FrankenPHP community!

I'm currently using the official FrankenPHP Docker image for my project, and I'm having some trouble configuring Xdebug to work seamlessly within this environment. I've followed the usual steps for Xdebug configuration, but it doesn't seem to be working as expected.

Here are the steps I've taken so far:

1. Installed Xdebug extension.
2. Updated php.ini with appropriate Xdebug settings.
3. Restarted the PHP service.

Despite these steps, I'm unable to connect my IDE (e.g., VSCode) to Xdebug within the FrankenPHP Docker container.

My environment details:

• Official FrankenPHP Docker image version: latest
• Operating System: Ubuntu 23.10
• PHP Version: 8.3.2-1
• IDE: PhpStorm

Questions:

1. Has anyone successfully configured Xdebug within the official FrankenPHP Docker image?
2. Are there any specific considerations or steps that need to be taken in FrankenPHP Docker environment?
3. Is there a recommended Xdebug configuration for FrankenPHP?

I would greatly appreciate any guidance or advice from the community on how to make Xdebug work seamlessly within the FrankenPHP Docker image.

Thank you for your help! 🙏

[adelynx]

Solved

The docker-php-extension-installer script is provided in the base image. Adding additional PHP extensions is straightforward:

FROM dunglas/frankenphp

# add additional extensions here:
RUN install-php-extensions \
    pdo_mysql \
    gd \
    intl \
    zip \
    opcache

[withinboredom]

If you look carefully at the docker compose file, it disables worker mode for xdebug. My IDE (PHPStorm) gives a different error than what you are seeing but when I reported the bug to them, they closed as "won't fix".

I am uncertain how worker mode would actually work with xdebug since it replaces global variables, references, etc under the hood. It will probably segfault even if we did get it to work.

[hazadam]

Oh, bummer. We'll that's good to know. This information would've saved me many hours of debugging. A good docs candidate 😆 . Thank you anyway 🙂

[withinboredom]

A good docs candidate

Indeed. However, I haven't needed worker mode + xdebug until very recently, and I've been using FrankenPHP since 2022 so it hasn't really come up.

[hazadam]

good news, I checked the source code once again and found that franken will pass env variables defined under given worker as $_SERVER variables.

	frankenphp {
	    num_threads 2
		worker {
		    file /app/public/index.php
		    num 1
		    env SERVER_NAME mailship.local
		}
	}

Then after configuring xdebug to start_with_request=yes and of coure correct client_host, PHPStorm would based on the newly added SERVER_NAME variable find path mapping and debugging now works as expected, that is in worker mode. 🙂

[withinboredom]

Interesting! I'll have to give that a go as well!