Sam Mela liked my WiPeD debugger for WordPress, but he wanted an easy way to include call traceback information.  So he added it, and he kindly shared his addition with me.

I’ve adapted what he did to my own tastes and included it in the download below.  Whenever you want to add the current call stack to the debug log, just call:

WPD_backtrace();

In order to test this, I added a new option in the Options page:

Trace the following actions (comma-separated)

Just enter the name of any action hooks on which you want to get a traceback added to the debug log.  This is not only useful for testing the plugin, it can also be used to find out where in the twisty little passages of WordPress each of the actions gets invoked.

Largely because of this feature, I now initialize this plugin whenever it is activated.  Previously I delayed setting it up until WPD_print was invoked.  So this plugin now imposes a small overhead if it is activated and not used.  Be advised.

I also adopted Sam’s idea of providing default styling (which I modified significantly).  If you don’t like it, you can remove or modify WiPeD.css.

Tony Peak (aka Rirath) helped to identify an incompatibility with PHP version 4 in my WiPeD plugin for WordPress.  Now, if back-porting to version 4 had involved a major rewrite I would have said “Routta Ruck, Rirath” — but it turned out to be pretty easy.  I had used class constants for the values in the database fields to indicate types of entries, and class constants weren’t supported in PHP 4.  Luckily, there’s a simple replacement:  define.  So, if you want to debug WordPress on PHP 4, download version 1.2 below.

So I was coding along one fine day, happily using my WiPeD debugger for WordPress, when I suddenly stumbled on a problem with it.  I was attempting to debug a function that was hooked to an action that was supposed to be triggered by the MetaWebLog API (‘save_post’, when posting from a blog authoring tool), and none of my debug messages were being displayed!  Suddenly the heel of my hand went *bonk* on my forehead — of course I couldn’t retrieve any messages from XMLRPC processing, because I was saving the messages in a session variable, and the client in that case is my authoring tool instead of my browser – so the sessions aren’t the same.  Duh, time to rethink.

The downloadable version below saves the debug messages to the database instead of to a session variable.  Obviously, that means that multiple users will mix their output in the log.  Of course, you’d expect to be debugging on a private site, but just in case I added an options page where you can exclude users based on their capabilities — with the default being ‘level_9′ (administrators only).  I also added options to allow you to customize when the debug log is displayed, as well as when it’s cleared.  Spin it up, and check out the Readme-WiPeD.txt file.

UPDATE: get the latest version here.

Speaking of the deficiencies of PHP, another one is the complete lack of built-in debugging capabilities.  Sure, you can find debuggers for PHP, if you’ve got the time and ability to configure them on your server.  I guess if I was really serious about PHP I’d have to get one of those, but so far I only use PHP for WordPress customization, so it hardly seems worth the effort.

Some people will tell you that you shouldn’t need a debugger.  That it’s a sign of lazy programming.  But PHP has so many pitfalls, and WordPress has so many actions and interactions between plugins and themes provided by so many different developers, that I think you’re excused if you need a little help figuring out just what the heck is going on in your code.

When writing a plugin or modifying a theme for WordPress, usually all I need to know is the order of events and the values in various variables.  Sometimes you can get away with inserting “echo” statements in your code — but sometimes you can’t, like when your code executes ahead of a “wp_head” action that wants to add headers.  Besides, randomly placed “echo” statements can easily get lost from view in the whirl of words and images that comprise your theme and content.

So, I developed a simple little plugin that collects debug statements and prints them out nicely above the footer of your theme, or below the admin footer, whichever gets executed first.  I call it WiPeD, for “WordPress Printf Debugger”.  Anywhere in your code, you can call WPD_print() and pass it whatever text you want to output.  The lines of text are aggregated in a session variable until they are output together (in separate divs, surrounded by a single containing div).  Thus you can use styling to set the messages off from the rest of your blog, if you desire.

Here’s an example, from a project I’m currently working on.  My plugin was producing no results, and I couldn’t figure out why.  So I added some calls to WPD_print():

Then, when I executed the code to trigger this action, here’s what I saw at the bottom of my page:

That tells me that I got into my function and passed the tests, but the post has no content at that point.  Now I just need to figure out why.

See the enclosed readme file for more details.  Have fun debugging your PHP!

UPDATE: get an updated version here.