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

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!