DIY WordPress: Debugging Plugins Using FirePHP

Hello there! If you are new here, you might want to subscribe to the RSS feed for updates on this topic.

(Reading time: 7 – 12 minutes)

You know you want to program WordPress plugins… but where to start? There’s so much to learn!

Turns out, programming WordPress plugins isn’t that hard, if you know how to use the right tools for the job. It’s no different than any other activity.

For example, you can cut just about anything with an axe: an oak tree, a loaf of bread, your leg (don’t ask ☹), whatever’s in the way. But a knife works much better.

Likewise, really sharpening your code requires exactly the right tool for the job, and a good debugger is essential.

To me, debugging so essential that I sneered at PHP and Ajax applications for years. Debugging code by printing variables and pressing CTRL-F5 is inefficient. There just weren’t very many easily available tools for PHP debugging, outside of installing (and learning) an entire application system such a Zend. That’s too much trouble!

FirePHP changes the landscape: debugging PHP just got radically easier.

Let’s do some WordPress PHP debugging

Website In A Weekend reader Michael W emails:

How do you debug PHP (e.g. for developing a new wordpress plug-in)? Do you use XDebug, FirePHP, or something else? A post about setting up and using one, or both, of these would be helpful.

I have succeeded in using XDebug and a windows-based debugging client (for debugging Ajax/REST requests between a jQuery front-end and a PHP back-end). I have installed, but not successfully used, FirePHP yet (haven’t worked on the server-side part).

Very timely question!

Debugging WordPress and plugins can be a real pain. Having tools for debugging is tremendously helpful. Practically necessary. I took a look at both XDebug and FirePHP. Of the two, FirePHP was a little more tractable, so I installed it on localhost. Here’s my experience.

Installing FirePHP debugging application

I chose to use a standalone version of FirePHP, installing using PHP’s pear facility on my Ubuntu Linux distribution running in VMWare:

doolin@doolin-ubuntu:~$ sudo pear channel-discover pear.firephp.org
Adding Channel "pear.firephp.org" succeeded
Discovery of channel "pear.firephp.org" succeeded
doolin@doolin-ubuntu:~$ sudo pear install firephp/FirePHPCore
downloading FirePHPCore-0.3.1.tgz ...
Starting to download FirePHPCore-0.3.1.tgz (22,630 bytes)
........done: 22,630 bytes
install ok: channel://pear.firephp.org/FirePHPCore-0.3.1

As it turns out, I was also able to install FirePHP using cygwin on Microsoft’s Window’s Vista as well. The key to installing on Vista was that my PHP installation is installed in Windows, not in cygwin, so I had to use “pear.bat” command. The pear commands would probably work as is with a cmd prompt in Windows.

Moving right along, I followed the instructions exactly and was able to run the FirePHP demonstration.

First test on hRecipe Plugin

Anytime I write a new plugin, I like to be reassured that the control of flow is proceeding normally. That is, how I want it to proceed. Specifically, I want to ensure that WordPress is reading and and activating the plugin correctly. FirePHP makes it easy to check: write to the console log when the plugin is loaded and when it’s activated.

First, we need to tell WordPress to load the FirePHP code, in this case using the object API. Here’s the code in hrecipe.php to make that happen:

43
44

require_once('FirePHPCore/FirePHP.class.php');
ob_start();

Next, let’s log the initialization function which is read every time Wordpress makes a sweep through the plugin directory:

if ( isset ($recipe)) {
 
    $firephp = FirePHP::getInstance(true); 
    $dt = date("l dS \of F Y h:i:s A");
    $firephp->log($dt,'date/time');
    $var = array('i'=>13, 'j'=>27);
    $firephp->log($var, 'if (isset())');
    register_activation_hook( __FILE__ , array ($recipe, 'hrecipe_activate'));

Line 55 ensures that all the necessary files were read correctly. If not, the plugin exits. Our next call will be triggered as a result of executing line 62. And here’s hrecipe_activate(), with the last logging call:

    function hrecipe_activate() {
 
       $firephp = FirePHP::getInstance(true); 
       $var = array('i'=>11, 'j'=>22);
       $firephp->log($var, 'Activate');

Let’s see what this looks like with FirePHP implemented in the WordPress hRecipe plugin. Firing up Firefox and enabling the Firebug/FirePHP addon results in the following console view:

FirePHP output from activating hRecipe plugin

The if (isset()) label (blue arrows) is emitted when the hRecipe plugin is read. The red box is the log message from the recipe class activation function. Activation functions require getting the path to the class file correct, which can be a bit tricky if the plugin name doesn’t match the file or directory names. The array values (13, 27) are meaningless; they have been kept as place holders for the next round of debugging.

Here’s something interesting which I did not know about WordPress: there is a function somewhere in the chain that refreshes the plugin directory once every minute. Here’s a screenshot showing what that looks like:

FirePHP showing 1 minute refresh

The red box shows the series of refreshes, in this case 13 seconds after each minute, shown in the orange boxes.

I’m assuming that this is normal behavior, because I am running this installation of WordPress on localhost. This is a pretty good assumption.

If I had discovered this behavior running from an external host, I would have seriously considered whether this was normal behavior or not. What if it wasn’t? Could mean I’d been hacked, but that’s a digression best left for the future.^†

These kinds of serendipitous discoveries are normal once you dig deeper using the right tools. I could have seen this using the Fiddler network debugging tool, had I known what to look for. With FirePHP, it showed me while I was looking for something else. Very convenient.

How FirePHP works

The short story:

FirePHP logs your debug messages to the Firebug console.

FirePHP consists of a server side library that allows you to examine any PHP variable without breaking the application’s response. That is, the application still works “the same” as it would without FirePHP by breaking the HTTP responses into parts.* Some parts of the HTTP response carry the usual application data (your PHP-generated webpage), other parts carry the FirePHP debugging data. You access this data using the FirePHP extension for Firefox (runs in the Firebug application).**

Last, but not least, FirePHP is distributed under a BSD license. If you don’t know what that means, it’s a good thing.