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
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
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
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.
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"
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):
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
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.
- Stop the debugging session
- Continue the session (run the entire page call)
- Step Over the current line
- Step Into the current line
- Step Out from the current line
- 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.
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.
Wow! I’m definitely giving this a try ASAP.
Awesome article, thanks for writing everything up. Installing Xdebug on my Mac has been a goal of mine for some time, and I plan on doing almost exactly the same process you outline above (though I use Drupal instead of WordPress ;-).
[…] Xdebug: Improve the WordPress development process. […]
If you want even more information garnered from Xdebug, you can set it to export profile/trace files which you can then run through a tool like kCacheGrind (*nix/OSX), WinCacheGrind (Windows), or Webgrind (OS agnostic, runs on a webserver) … in order of available information per tool.
[…] yet to see a bottleneck in the code space. I’ve also taken a step further in development by incorporating Xdebug into my workflow where appropriate and there’s not a shadow of performance degradation there […]
Excellent article Jonathan..
I’m definitely giving Netbeans a try, just to see what it has to offer. I’ve been working with Eclipse and Aptana (mutant remake of Eclipse) for a while and sort of happy with them, but setting breakpoints is damn near impossible due to path mapping issues (misconfiguration?).
It’s entirely exclusive to WordPress. I resorted to manually coding in xdebug_break() throughout my code, which IMO isn’t much different than showering the file with var_dump() and echo statements. Might as well drop the IDE’s and move back to good ole power couple – text editor and page reloads.
[…] Debugging WordPress With XDebug On December 3, 2011 In WordPress With No Comments https://jonchristopher.us/2011/03/28/wordpress-development-xdebug/ […]
Thanks a lot for the article! I’m gonna try and see if I can set it up. I’m a bit confused on which one of the precompiled versions of Xdebug I should get from the provided link if I’ve got PHP 5.3.1 on Mac
Many thanks in advance,
Hmm… I think I’ve figured out where to find the file and added it to the Apache files. Now I can see the Xdebug statistics when expecting phpinfo().
I’ve also installed MacGDBp, but quite confused on what to do now :S Could you explain that a bit further please?
I’m guessing that I need to echo or var_dump my variable that I want to expect. Do I need to do any kind of settings to make sure it appears in the MacGDBp? I got confused by Xdebug doc saying that you need to start it before you can see the variable info.
I would hugely appreciate if you could explain more on how to use MacGDBp with Xdebug or point me in the right direction.
Very good write up. You can get xdebug, wordpress, apache, and mysql with support for ‘fake’ domain names in a free package that’ll work with NetBeans right ‘out-of-box’ so to speak…