Using Xdebug within Local

What is Xdebug?

Xdebug is an extension for PHP that helps you with debugging and developing applications.

You’ve probably already run into Xdebug and not been aware of it. The most obvious improvements are:

  1. Improved formatting of the var_dump() PHP function.
  2. More informative notices, warnings, and errors.

Because Xdebug does include more information about what is happening when things go wrong, it’s often enabled in development environments like Local.

The above improvements are awesome, but Xdebug also includes a powerful step debugger that is essential for debugging the most complex issues of a PHP project.

Xdebug Features

Let’s take a closer look at the main features of Xdebug and how we can make use of them within Local and WordPress.

Improvements to var_dump()

The easiest way to dive into an issue and see what’s happening is by using PHP’s var_dump(). Sure, it’s a little hacky to do, but it’s also quick and, more often than not, enough to get you what you need.

Without Xdebug, you have to remember to format PHP in a specific way. When Xdebug is enabled, calling var_dump() produces output that’s both readable and useful.

A screenshot showing the difference in var_dump output between having Xdebug enabled and having Xdebug disabled.
When Xdebug is enabled, the output of var_dump()is more structured and easier to read.

Better Notices, Warnings, and Errors

When troubleshooting, one of the most helpful things is to get an idea of where exactly an error is occurring. Xdebug will improve the messages that PHP gives by providing a stack trace. You can think of a stack trace as a list of functions called before the error was encountered.

A screenshot showing the difference in PHP messages between having Xdebug enabled and having Xdebug disabled.
The same breaking code (calling a non-existent function) displays differently depending on if Xdebug is enabled or not.

note

If you’re still new to doing PHP development, this “feature” of Xdebug can be confusing. You might be asking yourself:

“Why does my site look broken in Local but not on Production?”

In some cases, this is because Xdebug enhances these messages (notices, warnings, errors) to make them more “noisy.”

To learn more about this as well as how to configure PHP messages in Local, see the related Help Doc:

Step Debugger

Often, when people think of Xdebug, the step debugger is what comes to mind. This feature allows you to interactively walk through your code and inspect the application’s state at specific points in time.

Each of those points in time is specified by creating a “breakpoint” within the editor. The editor communicates with Xdebug to pause the application at that specific point in the code.

Using Xdebug’s step debugger with VS Code to investigate the call stack and variables within WordPress’ default TwentyTwentyOne theme header.

Traditionally it’s been challenging getting Xdebug and your editor of choice to communicate with each other. Local has two Add-ons that help make that configuration process easy; one for PHPStorm and one for VS Code.

Step Debugger Local Addon: Xdebug + VS Code

This Local Add-on helps to configure the connection between Xdebug and VS Code. For more information or to help with development, take a look at these links:

Step Debugger Local Addon: Xdebug + PHPStorm

This Local Add-on helps to configure the connection between Xdebug and PHPStorm. For more information or to help with development, take a look at these links:

Other Editors

If you have a different editor, you may still be able to use Xdebug’s step debugger within Local. I recommend taking a look at Xdebug’s documentation for specific setings:

Each site’s PHP configuration can be found within the site folder within the PHP.ini file for the site, which can be found in the conf folder:

site-name/conf/php/php.ini.hbs

Make sure to restart the site after any changes to this file so that Local can re-compile those settings for the site.