How do I get xdebug/step-debugging working with ddev? - phpstorm

Question

I've been working with ddev on my Drupal projects, and now want to use xdebug so I have step-debugging with PhpStorm (or really any IDE would be fine). But I can't seem to get it to stop on breakpoints. I tried to follow the instructions in ddev docs but that doesn't do get me going, and I don't know what to do next. I did:
Set the 172.28.99.99 IP address as discussed there
Enabled xdebug using config.yaml xdebug_enabled: true and ddev start (and checked with phpinfo to see that xdebug was enabled.)
Put PHPStorm in "listen for debug connections" mode

Answer 1

Debugging xdebug in any setup can be a little trouble, but here are the steps to take:
First, reread the docs. You may want to read the troubleshooting docs rather than this issue, since they're maintained more often.
Make sure xdebug has been enabled; it's disabled by default for performance reasons. Most people use ddev xdebug on to enable it when they want it, and ddev xdebug off when they're done with it, but it can also be enabled in .ddev/config.yaml.
Don't assume that some obscure piece of code is being executed and put a breakpoint there. Start by putting a breakpoint at the first executable line in your index.php. Oh-so-many times people think it should be stopping, but their code is not being executed.
ddev ssh into the web container. Can you ping host.docker.internal (and get responses)? If you can't, you might have an over-aggressive firewall.
In PHPStorm, disable the "listen for connections" button so it won't listen. Or just exit PHPStorm.
ddev ssh: Can telnet host.docker.internal 9003 connect? If it does, you have something else running on port 9003, probably php-fpm. Use lsof -i :9003 -sTCP:LISTEN to find out what is there and stop it, or change the xdebug port and configure PHPStorm to use the new one . Don't continue until your telnet command does not connect.
Now click the listen button on PHPStorm to start it listening for connections.
ddev ssh and try the telnet host.docker.internal 9003 again. It should connect. If not, maybe PHPStorm is not listening, or not configured to listen on port 9003?
Check to make sure that Xdebug is enabled. You can use php -i | grep grep Xdebug inside the container, or use any other technique you want that gives the output of phpinfo(), including Drupal's admin/reports/status/php. You should see with Xdebug v2.9.6, Copyright (c) 2002-2020 and php -i | grep "xdebug.remote_enable" should give you xdebug.remote_enable: On.
Set a breakpoint in the first relevant line of the index.php of your project and then visit the site with a browser. It should stop there.
A note from #heddn: If you want to have xdebug running only for fpm, phpenmod -s fpm xdebug for example, instead of running enable_xdebug.
A note from #mfrieling: If you use a browser extension like XDebug Helper which sets an IDE key, that must be the same as on the server. Since DDEV 1.10.0 "there's a real user created for you inside the web and db containers, with your username and userid" which is also used as IDE key by default. The used IDE key must be the same on the server, the browser extension/cookie sent and PHPStorm. You can change the IDE key in DDEV by creating a file .ddev/php/xdebug.ini with the following two lines (replace PHPSTORM with the value you want use:
[XDebug]
xdebug.idekey = PHPSTORM
Your followups are welcome here!

Answer 2

Thanks, had the same problem and adding the file .ddev/docker-compose.xdebug.yaml fixed the issue.
However, I am running on a Mac / OSX and found these additional steps worked to discover the IP address of the internal host from inside the container:
1.) Log into the web continaner ddev ssh
2.) Run ping docker.for.mac.localhost
3.) Set the returned IP address for host.docker.internal in the above yaml file.
4.) Remove and start the DDEV.
Also worth mentioning validating xdebug in PHPStorm is useful to check the config.

Answer 3

Careful with Macs, as they may have php-fpm running. If it's the case PHP Storm won't find the connection (as it's already taken by php-fpm).
To see if it's the case run:
lsof -i :9000 -sTCP:LISTEN
if it returns something like php-fpm, then you have this issue
Try closing it (see PHP-FPM can't be closed ).
Running it once you have fixed it (potentially restarted your mac) you should see something like this:
➜ solrpoc lsof -i :9000 -sTCP:LISTEN
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
phpstorm 512 alejandro.moreno 490u IPv6 0xaf3eef0f3233a83 0t0 TCP *:cslistener (LISTEN)