Search code examples
dockermacosphpstormxdebug

Xdebug inside Docker on Mac is not working

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://[email protected]: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

enter image description here

Solution

  • 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

    enter image description here

    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.