Over the past few years, we've published a couple of blog posts about setting up Xdebug for Drupal module development. But, like all things in tech, there's always more to learn as tools and technology evolve.

The setup

I was recently working with one of our Professional (Drupal) Module Development students trying to determine why she wasn't able to use Xdebug to debug a PhpUnit-based functional test. To be clear, the breakpoint wasn't set in the actual test class, the breakpoint was set in some custom module code that was called by the test class.

In functional tests, Guzzle is used by PhpUnit to make calls like:

$this-&gt;drupalGet('<front>')</front>

So, in a way, there isn't a direct PHP connection between test class and the code under test. It is in this circumstance that the breakpoint wasn't working.

Xdebug was working fine for this student to debug other aspects of the same project - it just wasn't hitting breakpoints during functional tests.

The solution

This was one of those instances that I had seen (and solved) previously, but to be honest, PhpStorm/Xdebug solutions have often involved numerous trips into the (extensive) PhpStorm settings area. By the time the problem is fixed, I was never 100% sure exactly which change I made had actually solved the problem. But, this time, I was more careful…

Obviously, Xdebug must be enabled in DDEV, and PhpStorm's almost-magical auto-configuration for Xdebug needs to have configured a new "Server" with proper path mappings (especially for the project root).

The PhpStorm configuration settings related to Xdebug that I now recommend are:

• Set the "Max connections" value to 20 in the "PHP | Debug" configuration area (see image above).
• Uncheck the “Force break at the first line when no path mapping is specified,” "Force break at first line when a script is outside the project" and "Ignore external connections through unregistered server configurations" checkboxes in the "PHP | Debug" configuration area (see image above.)
• Set "Host" and "Name" in the "PHP | Servers" configuration are the same (and of the form name.ddev.site, where name is your site's DDEV machine name) (see image below.)
• When running functional tests, PhpStorm may request to see up a new server connection in "PHP | Servers" with the name "localhost." Allow it and ensure the path mapping is correct.

With these settings, functional PhpUnit tests can be effectively debugged.