Connection was not established. Probably 'xdebug.remote_host=host.docker.internal' is incorrect. Change 'xdebug.remote_host'

I'm trying to use Xdebug (v3) through PhpStorm (v2022.3.2) to debug a PHPUnit test method from inside a Docker container.

Xdebug is correctly setup and also the server in PhpStorm is.

In fact, if I run tests from command line, Xdebug stops at breakpoints:

XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=myapp.localhost" vendor/bin/phpunit --testdox --filter testProfileUpdate

If I debug the test clicking on the "bug" icon on the left of the test method, instead, I receive the following error:

Connection was not established. Probably 'xdebug.remote_host=host.docker.internal' is incorrect. Change 'xdebug.remote_host'.

Looking at the command executed by PhpStorm to debug a test method, here is what I see:

[docker://myapp:latest/]:php -dxdebug.mode=debug -dxdebug.client_port=9000 -dxdebug.client_host=host.docker.internal /opt/project/vendor/phpunit/phpunit/phpunit --configuration /opt/project/phpunit.xml --filter "/(ProfileTest::testProfileUpdate)( .*)?$/" --test-suffix ProfileTest.php /opt/project/tests --teamcity

Tried to configure two more flags

I've also tried to configure two more flags:

-dxdebug.idekey="serverName=myapp.localhost"
-dxdebug.session=1

The resulting command is this:

[docker://myapp:latest/]:php -dxdebug.mode=debug -dxdebug.client_port=9000 -dxdebug.client_host=host.docker.internal -dxdebug.idekey="serverName=myapp.localhost" -dxdebug.session=1 /opt/project/vendor/phpunit/phpunit/phpunit --configuration /opt/project/phpunit.xml --filter "/(ProfileTest::testProfileUpdate)( .*)?$/" --test-suffix ProfileTest.php /opt/project/tests --teamcity

Also with this configuration, Xdebug doesn't start and breakpoints are ignored (and the error message pops up).

Tried to disable params passed by PhpStorm

I tried to disable params passed automatically by PhpStorm going to Settings > PHP > Debug.

Then, in the section "Advanced settings" I unflagged the option "Pass required configuration options through command line".

Now, the resulting command is this:

[docker://myapp:latest/]:php /opt/project/vendor/phpunit/phpunit/phpunit --configuration /opt/project/phpunit.xml --filter "/(ProfileTest::testProfileUpdate)( .*)?$/" --test-suffix ProfileTest.php /opt/project/tests --teamcity

As you can see, there is no mention of xdebug.client_host nor of xdebug.remote_host.

Nevertheless, PhpStorm continues to pop up the same error mentioning xdebug.remote_host=host.docker.internal.

I imagined that an error should have occurred, but different, something saying a required parameter is missed.

Request for help

Any idea about how to configure PhpStorm to start an Xdebug session to debug a PHPUnit test?

Solution

-dxdebug.client_port=9000

Xdebug 3 now uses 9003 port by default instead of 9000. Try sticking to this.

In PhpStorm you most likely have both old and new ports listed (9000,9003 as a default value) to cover new and old Xdebug versions. But it uses the first in a list for CLI scripts (which PHPUnit is)...

Either remove it (preferred; so you will only have 9003 there) or make it last (i.e. 9003,9000). It's a per-project setting so you can use old 9000 port in another project if needed.

-dxdebug.idekey="serverName=myapp.localhost"

This will not work (wrong approach). You are trying to pass it as Xdebug IDEKey param... but it actually should be the value of the ENV variable named PHP_IDE_CONFIG.

If you want to actually use it:

Look into the PHPUnit config file: it has the ability to set up custom ENV variables for tests.
Another place: PhpStorm's Run/Debug Configuration for PHPUnit has an Environment variables field: try using it for this purpose.
Or use it in your actual docker file/config.

Other than that: enable Xdebug log (xdebug.log), try to debug (both when it's working and when it's not) and see what the log has to say for both runs (where it connects to, what the response is etc). You should spot the difference that should give the clues on what might be wrong (in which direction to dig further).

This actually should be the first step when investigating "why it works here and not there" situations.