Xdebug inside Docker on Mac is not working

Question

I ported a local development setup from Linux to a new Mac machine and am having problems with getting Xdebug to work with PhpStorm in a Mac M1 Pro machine.

I have one container with PHP where Xdebug is installed and configured like this:

zend_extension=/usr/lib/php8/modules/xdebug.so
xdebug.mode=debug

xdebug.idekey=PHPSTORM
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.discover_client_host=1
xdebug.log=/var/log/xdebug.log

In PhpStorm I am listening to port 9001 (I use 9000 for other service).

Here are Xdebug logs inside docker container at /var/log/xdebug.log

/var/www/html/app # tail -f /var/log/xdebug.log 
[49] [Step Debug] INFO: Checking header 'HTTP_X_FORWARDED_FOR'.
[49] [Step Debug] INFO: Checking header 'REMOTE_ADDR'.
[49] [Step Debug] INFO: Client host discovered through HTTP header, connecting to 172.18.0.4:9001.
[49] [Step Debug] WARN: Creating socket for '172.18.0.4:9001', poll success, but error: Operation in progress (29).
[49] [Step Debug] WARN: Could not connect to client host discovered through HTTP headers, connecting to configured address/port: localhost:9001. :-|
[49] [Step Debug] WARN: Creating socket for 'localhost:9001', poll success, but error: Operation in progress (29).
[49] [Step Debug] WARN: Creating socket for 'localhost:9001', connect: Address not available.
[49] [Step Debug] ERR: Could not connect to debugging client. Tried: 172.18.0.4:9001 (from REMOTE_ADDR HTTP header), localhost:9001 (fallback through xdebug.client_host/xdebug.client_port) :-(
[49] Log closed at 2022-03-15 16:28:46.957669

I don't understand why the connection is not happening/failing.

Also I have a docker-compose.yml file that has the service API above as

  api:
    build:
      context: .
    expose:
      - 8080
    container_name: api

What I tried already ?

1. Changed xdebug.ini config to use remote host docker.for.mac.localhost, then host.docker.internal but no success.
2. Changed start_with_request=trigger instead of yes.
3. Disabled Mac firewall thinking that maybe port 9001 cannot be used by Docker.

Update 19 August 2022 - This does not work debugging cli scripts (phpunit tests)

The provided answer with config below is working via HTTP requests but not for phpunit tests or cli scripts.

Content of /etc/php8/conf.d/50_xdebug.ini

                                                                                 
zend_extension=/usr/lib/php8/modules/xdebug.so
xdebug.mode=debug

xdebug.idekey=PHPSTORM
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log=/var/log/xdebug.log

Debugging does not work and I get the error below

Xdebug: [Step Debug] Could not connect to debugging client. Tried: 172.18.0.1:9001 (through xdebug.client_host/xdebug.client_port) :-(

When my editor PhpStorm tries to run this

[sshConfig://api-root@docker.dev:2023]:/usr/bin/php -dxdebug.mode=debug -dxdebug.client_port=9001 -dxdebug.client_host=172.18.0.1 /var/www/html/app/vendor/phpunit/phpunit/phpunit --configuration /var/www/html/app/phpunit.xml --filter "/(Tests\\Unit\\App\\Services\\Maps\\GoogleMapsServiceTest::testGetPlaceFromId)( .*)?$/" --test-suffix GoogleMapsServiceTest.php /var/www/html/app/tests/unit/app/Services/Maps --teamcity

And also the /var/log/xdebug.log logs inside the docker machine

[326] [Step Debug] INFO: Connecting to configured address/port: 172.18.0.1:9001.
[326] [Step Debug] WARN: Creating socket for '172.18.0.1:9001', poll success, but error: Operation in progress (29).
[326] [Step Debug] ERR: Could not connect to debugging client. Tried: 172.18.0.1:9001 (through xdebug.client_host/xdebug.client_port) :-(
[326] Log closed at 2022-08-19 16:24:59.855397

I fixed this with a hacky way by modifying phpunit interpreter configuration. I am not sure why the /etc/php8/conf.d/50_xdebug.ini value set to internal docker host was ignored in this case

Answer 1

xdebug.discover_client_host=1 is most certainly not correct for use with Docker, you need to set that to 0. discover_client_host uses the HTTP headers to see where the request came from, but as NAT gets involved with Docker Xdebug (and PHP) will see an IP address or host name it can not connect to.

Setting xdebug.client_host=host.docker.internal should be correct with Docker, and this should be the network gateway address, which is what your host is too.

(Even if xdebug.discover_client_host=1, as Xdebug will fall back to the xdebug.client_host setting if it can't connect to the incorrect one it found with HTTP header discovery.)

If you want to see more detailed logs, also add xdebug.log_level=10, which should give more insight.

You don't need "bind port" in docker-compose.yaml for Xdebug, as Xdebug does make the connection to the IDE, and hence the port does not need to be exposed for receiving connections.

Answer 2

Solution for running phpunit (or any cli script) in debug mode via

The configuration inside your docker running container at

/etc/php8/conf.d/50_xdebug.ini needs to be like below

zend_extension=/usr/lib/php8/modules/xdebug.so
xdebug.mode=debug

xdebug.idekey=PHPSTORM
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log=/var/log/xdebug.log

but that is not enough.

You have to set manually the Configuration Option in the interpreter for

xdebug.client_host

to equal host.docker.internal inside PhpStorm interpreter configuration

This is somehow ignored and not read from the config file /etc/php8/conf.d/50_xdebug.ini during cli mode and I was having issue for tests debug not working while web http requests were working fine.