Xdebug 3 is out, and you’ll need to update your settings

As a PHP developer (and particularly as a user of PhpStorm), I’m a huge fan of using Xdebug for step debugging my applications. If you’ve worked with me for any length of time, I’ve already evangelized to you about these tools, most likely ad nauseum. For the rest of you, perhaps that’s a tale for another time: the short answer is, Xdebug makes it easy to work with PHP applications and understand data state during runtime, and PhpStorm itself makes it easy to connect to Xdebug.

For newer developers, or developers who use a different IDE, or developers (like me) who sometimes struggle a bit to read the docs, configuration can be a challenge. And sometimes, troubleshooting a configuration even more so.

All that said, there are loads of examples on the web for a basic step debugging configuration for Xdebug. They typically look something like this:

[Xdebug]
zend_extension=/path/to/your/xdebug.so

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.idekey=PHPSTORM

# For configurations that require a different default port
xdebug.remote_port=9001

Configuration for Xdebug 3

Almost every line in the above configuration has changed with Xdebug 3. As such, when you upgrade, you’ll also need to update your php.ini file (or xdebug.ini, or wherever it is that you store your PHP module configurations). The equivalent to the previous example is:

# Configuration for Xdebug 3
[Xdebug]

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.idekey=PHPSTORM

# For configurations that require a different default port
xdebug.client_port=9001

# Note: Xdebug 3's default port is now 9003 instead of 9000,
# so even if you don't use this setting, you'll still 
# need to update your IDE settings to get it to connect.

Derick Rethans has published a guide to upgrading from Xdebug 2 to 3 that details the many changes between versions. Importantly, it simplifies a lot of the configuration, and some of the options are now grouped into a single value. For instance, if you want to enable step debugging, but you also want to continue seeing stack traces, you can pass in a comma-separated set of values to xdebug.mode:

xdebug.mode=debug,develop

As usual, there are many different options that I’m not going to cover in this very short post. Importantly, however, there are enormous performance benefits to this new release, and it’s backward-compatible to PHP 7.2. If that meets your needs and you’re already a user of Xdebug, I highly encourage you to upgrade today, and to consider donating to the continued development of the project.

Update: November 30th

I’ve discovered at least one item of interested since publishing this post last Thursday:

Setting xdebug.start_with_request to yes is the equivalent to always having Xdebug running. With Xdebug 3, this will also generate a PHP warning in your logs with every request you make that doesn’t have a client listening on your debug port. This might be less-than-ideal for development scenarios when you only want to trigger Xdebug when you’re actually debugging. In this case, you should set the value to trigger instead.

The trigger setting for xdebug.start_with_request changes the behavior slightly: it requires that you pass a value to your $_GET or $_POST request in the browser to get Xdebug to listen (or to activate a browser extension such as Xdebug Helper for Firefox) in addition to triggering debugging in your client, such as PhpStorm.

On the WordPress development side, I’m still tinkering with Xdebug 3 to understand how to correctly trigger the debugger from the CLI. The upgrade guide documentation seems clear about what needs to happen (e.g., setting an environment variable before running a PHP script), but it doesn’t seem to be triggering for me. I’ll possibly update this post again and or create a new post with additional findings once I get that sorted.

In the short-term, setting xdebug.start_with_request to yes does in fact make it easy to trigger breakpoints easily in either the browser or the CLI, but until I find a way to disable the warnings to my PHP error logs, it’s not my preferred approach.