Improving Your Process: WordPress Development Using Xdebug

I not too long ago changed the way I worked on both client work and my WordPress plugins. It spawned a diversion from my comfort using a text editor and has me seriously considering a switch to an IDE. The underlying root though, was my desire to increase both productivity and quality when programming. I was swimming in repeated echos and print_r()s. While they get the job done, it’s sloppy. I found myself tracking and printing variables (usually multiple times) just to make sure things were happening as I had planned.

Enter Xdebug: the demise of print_r()

I first started messing with Xdebug years ago when I first heard it mentioned in passing while reading an article. I was more into front end and JavaScript at the time and wasn’t doing much professional programming. Interest pretty much fizzled at that point, although I thought it was neat at the time, I guess. I’m glad I stumbled upon Xdebug because as I was auditing potential IDEs to check out, I saw it mentioned on many feature lists as being the underlying built-in debugging component of various environments. A bit of research later and I knew Xdebug would likely be a big deal for my workflow.

Xdebug is best summarized as: (more on Wikipedia)

Xdebug is a PHP extension which provides debugging and profiling capabilities. It uses the DBGp debugging protocol.

The debug information that Xdebug can provide includes the following:

• Stack and function traces in error messages with:
  • Full parameter display for user defined functions
  • Function name, file name and line indications
  • Support for member functions
• Memory allocation
• Protection for infinite recursions

Xdebug also provides:

• Profiling information for PHP scripts
• Code coverage analysis
• Capabilities to debug your scripts interactively with a debugger front-end

After reading that, the only question I had for myself was why did I wait so long?

Installing and configuring Xdebug

There are some official docs on installing Xdebug, which is likely the most difficult part of working with it. Depending on your environment, you may have to recompile PHP in your development environment, else you can use PECL or a precompiled version. Lukcily, there seems to be precompiled versions of Xdebug for just about everything, so I’d suggest using that, graciously provided by ActiveState. It’ll make your life much easier.

You’ll need to know which version of PHP you’re using, and the download provided by ActiveState will have either an xdebug.so or php_xdebug.dll (Windows) ready to go for you.

My personal development environment is a MAMP Pro server, so I’ll detail how you integrate Xdebug in MAMP. The process is similar for your environment; Xdebug is a PHP extension, so you’re going to need to edit your php.ini and make the changes outlined here.

Disable Zend Optimizer

Zend Optimizer and PHP caching systems interfere with Xdebug, so your first step will be to disable those.

Edit php.ini

MAMP uses templates for server configuration files, including php.ini — you’ll need to edit that. Ensure you’re editing the php.ini that matches your active version of PHP.

Near the bottom will be a [Zend] flag with some config for Zend, ensure that it’s commented out, if it wasn’t using the GUI for MAMP Pro.

We’ll be adding a new section for Xdebug (Note: Ensure the zend_extension path matches your system path)

[xdebug]
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1
zend_extension="/PATH/TO/YOUR/xdebug.so"

Restart Apache

Once you’ve saved your php.ini, restart Apache and view your phpinfo(), there should be an entire section for Xdebug

With Xdebug installed and running, we can get to the fun part.

Working with Xdebug and WordPress

There are a number of articles out there that describe how to get up and running with Xdebug for general PHP development, but I’m using it for WordPress work, and thought it might be better to tailor usage to that. Here goes.

The first thing to work though here is how you’re editing your code. There was a time where I thought debugging was a major reason to go with an IDE. I was wrong. Kind of. While debugging is an ingrained feature of an IDE, there are ways to use your favorite text editor in conjunction with Xdebug. Some text editors have extensions specific to Xdebug, and if you’re on a Mac, you’ll joy in finding out about MacGDBp. MacGDBp is a standalone application you can run for the specific purpose of talking to an Xdebug session. I’d argue to say that it’s even easier to work with than your IDE. All you have to do is run the app and hit the site you’re working on.

Setting things up in your IDE is a bit different, you’ll likely need to edit a preference or two. Debugging is also a bit different in that you’ll need to actively start and stop a debugging session. Your preference will dictate which you like better. NetBeans makes it pretty easy to work with Xdebug by checking out Preferences > PHP > General:

If you used the settings snippet for php.ini from above, your Xdebug sessions will run on port 9000 and you should be good to go. To invoke a debugging session in NetBeans you’ll be using the Debugging Toolbar primarily, and you can begin a debugging session by hitting the appropriate button (or hitting CMD+F5):

Variable tracing

By far the biggest benefit to using Xdebug for me is tracing variables. After all, the major inspiration for exploring the extension was to get away from extraneous echos and print_r()s. Depending on which piece of software you’re using (MacGDBp or IDE) the visuals will be a bit different, but the concept is the same. When you invoke your debugging session, execution will pause at the first line, giving you a few options.

1. Stop the debugging session
2. Continue the session (run the entire page call)
3. Step Over the current line
4. Step Into the current line
5. Step Out from the current line
6. Run to the cursor (not found in MacGDBp)

Note: One of the reasons I really like using an IDE (NetBeans specifically) is that this data is integrated into the environment (redundant to say that, I realize) to the extent of integrating breakpoints and all the way down to current memory usage:

The actions available during each step of execution are what really shows the magic of Xdebug. You can literally watch WordPress build a page, step by step, function call by function call, pausing execution to check out variables at any point.

As you step through, you can watch your variable stack change with every line executed, along with watching each function execute to see what is getting passed where:

In addition to checking out real-time variable values, another huge benefit to using Xdebug is stack tracing; finding out which functions were executed and when.

Breakpoints in Xdebug

While variable and stack tracing are a huge part of debugging, stepping through the entire execution of a WordPress page is extremely time consuming. I’d suggest checking it out to at least see how much work WordPress is doing on every page load. It’ll give you a look at WordPress in a way you likely haven’t seen it before. Breakpoints help alleviate that issue and allow you to debug what you’re actually working on.

You can think of a breakpoint as a stopping or pausing place during the execution of your program. You’ve likely heard of breakpoints in JavaScript development, and the same principle applies here. Working with breakpoints is another reason it helps to be using an IDE. The IDE itself will allow the setup and maintenance of breakpoints and everything is in one place. With a standalone application like MacGDBp you’ll be editing code in one place, and your breakpoints in another. More on that later.

Setting up a breakpoint is as easy as flagging the line of PHP at which you’d like to break as a breakpoint.

Setting up a breakpoint will tell Xdebug to run until it hits said breakpoint, allowing you to avoid having to step into every function call leading up to your custom work. Execution will pause at your breakpoints, allowing you to inspect the environment in real time, specially tailored to the piece you’re currently working on.

Setting up breakpoints in a standalone application such as MacGDBp requires that you manually edit the breakpoint by browsing to the file by hand and setting up breakpoints within MacGDBp itself.

Execution will pause at the breakpoint, and you can inspect things as you normally would.

Breakpoints will likely be a most used feature should you get more into debugging with Xdebug, and I can already tell it’s going to have a huge impact on the way I work. That said, I realize I’ve just scratched the surface with using Xdebug, and I can’t wait to more fully explore the innards of WordPress and learn more about what it’s actually doing under the hood.