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

Answer 1

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 2

Debugging xdebug in any setup can be a little trouble, but here are the steps to take:

• First, reread the docs.
• Make sure you have a 2019+ version of PHPStorm. Many PHPStorm versions up to and (including?) 2018.3 were incompatible with newer XDebug versions.
• Make sure xdebug has been enabled; it's disabled by default for performance reasons. Most people use ddev exec enable_xdebug to enable it when they want it, and ddev exec disable_xdebug 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 9000 connect? If it does, you have something else running on port 9000, probably php-fpm. Use lsof -i :9000 -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 9000 again. It should connect. If not, maybe PHPStorm is not listening, or not configured to listen on port 9000?
• 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!