DEV Community

Docker, PHPStorm and Xdebug, The definitive guide

Bruno Paz on September 06, 2018

Docker has changed dramatically the way we develop applications. Thanks to it, it is really easy for everyone to run a complex application with a ...

Read full post

Seymos76 • Oct 30 '18

Hi ! I followed this guide three times but getting this message in Xdebub :
Waiting for incoming connection with ide key 'PHPSTORM'

The URL i loaded in my browser : localhost:8888/?XDEBUG_SESSION_STA...

Please, i need some help, i don't understand why it's not working...

Bunyamin Inan • Aug 1 '19

I face the same problem.

Bunyamin Inan • Aug 1 '19

Ok, in my case, my ip address was different. Please check your IP address.

Matthew Phillips • Jul 1 '19

Awesome article, thanks. Couple of points I came across:
1) Running docker-compose up on the demo rep doesn't "just work". I didn't dig in, just a heads up
2) For any else coming across this as dim as I am - be aware that you must have Php and Xdebug installed locally in order for this to work!

Alexander Morozov • Sep 14 '18

Hmm, it seems like it's not working on MacOS. Project start is ok, but no debug. I'l try to find correct solution for mac

Alexander Morozov • Sep 17 '18

Ok, I found a correct solution for mac. You should use docker.for.mac.localhost instead 192.168.1.102 in .env file for remote_host. And you must enable DBGp proxy in phpstorm setting. Use IDE key: PHPSTORM, Host: docker.for.mac.localhost.
And I have xDebug configured locally on mac, and use 9002 port for debug instead 9001.

Stanislas • May 2 '19

Thank you so much! 🙏

Yaron Uliel • Jul 25 '19

After waisting a few hours - I think it is also worth mentioning that you must also have xdebug.remote_connect_back set to 0 - otherwise it won't initiate the connection from server php-fpm

vbourdeix • Mar 27 '19

Thanks for the article, but I could not test :

For some reason, the nginx container crashes at startup so I cannot test :

docker-compose up
Starting symfony-docker-xdebug-demo_php_1 ... done
Recreating symfony-docker-xdebug-demo_nginx_1 ... done
Attaching to symfony-docker-xdebug-demo_php_1, symfony-docker-xdebug-demo_nginx_1
php_1    | standard_init_linux.go:207: exec user process caused "no such file or directory"
nginx_1  | 2019/03/27 15:35:15 [emerg] 1#1: host not found in upstream "php" in /etc/nginx/conf.d/default.conf:10
nginx_1  | nginx: [emerg] host not found in upstream "php" in /etc/nginx/conf.d/default.conf:10
symfony-docker-xdebug-demo_php_1 exited with code 1
symfony-docker-xdebug-demo_nginx_1 exited with code 1

It seems that docker cannot resolve the php hostname, which is weird because I use a similar configuration for other projects without any issue.

Josep (Joe) Bigorra • Dec 10 '19

Bom dia Bruno, a fellow portuguese kindly needs your help.. In my job we are running PHPStorm to manage our API that was made with Laravel, and runs many async processes with Laravel Jobs and Events, which makes it practically impossible to debug at certain points.. I have tried to change my queue driver to sync but that results in my jobs not working.. Do you have an idea how to debug my async tasks?? Thanks

Patrik Kristian • Sep 7 '18 • Edited

I never got into Xdebug thing and a little bit started with that. Then fire nation attacked. I mean i started use docker and i was on zero again.
So thank you for this guide, complete and i hope foolproof (will see when i will do that), i love that :)

lainosantos • Apr 21 '19 • Edited

Hi,
On linux with firewalld enabled, the container hasn't route for host, so it not attach to host port 9000 (xdebug). The route can be add by:
firewall-cmd --zone=public --add-rich-rule='rule family="ipv4" source address="172.17.0.0/16" accept'

Where 172.17.0.0 is docker container's subnet (check it with ifconfig).

Shahroz Nawaz • Apr 4 '19

Nice article but my love is for VSCode so I've written a guide for integrating Xdebug in VSCode for PHP debugging. You can read it here: cloudways.com/blog/php-debug-with-...

Bruno Paz • Apr 6 '19

Nice! I also love VSCode and would really like to use it as my single Editor, but its autocomplete and refactoring features are still very behind of Jetbrains IDEs.

I tried a couple of extensions but none of seem to work consistently.

JeruPogi • Jun 24 '21

is this fixed for mac? Thanks!

BaronVonHex • Oct 17 '18

Thanks Bruno! I use VS code but your guide was great help! Just switched my dev environment from vagrant managed VMs to docker containers and It's beautiful :D