(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:
55 56 57 58 59 60 61 62 | 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:
7 8 9 10 11 | 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.
Read more about FirePHP
The official FirePHP website is probably the first place to visit for getting started. All the information you need for installing and using the addon is there.
Christoph Dorn presents Integrating FirePHP for Ajax Development, an excellent guide for getting started with FirePHP and one of the primary references for this article. In his own words,
My purpose in this column is to introduce you to FirePHP, the problem it solves, and how it is intended to work within your application for maximum benefit. I will present some useful high-level knowledge to make it easier for you to integrate FirePHP into your application.
Dorn continues, covering a few basic methods for debugging PHP, noting that learning some Javascript along the way is probably a good idea, and explaining the FirePHP architecture.
Six Revisions weighs in with How to Debug PHP Using Firefox with FirePHP, another excellent article for getting started. Here’s what the author Nuno Franco da Costa has to say:
FirePHP is an add-on for an add-on: it extends the popular in-browser web development tool called Firebug with an API for PHP web application developers. FirePHP is free and easily attainable via the Mozilla Add-Ons section on the official Mozilla site.
da Costa goes further into logging than we did here, and covers Information, Warning and Error log messages.
Turing Tarpit offers a WordPress logging plugin based on FirePHP code: WordPress Logger: A plugin that displays log messages to the Safari and Firefox console from PHP. Chandima Cumaranatunge provides this great list of WordPress logging features:
- Log debug messages directly from themes and plugins.
- Display log messages in the browser console, without muddying up the browser display.
- Displays complex structures such as arrays and objects in pretty print.
- Shows the line number and file from where the message was logged (you won’t lose track of log statements).
I’ll be checking out this WordPress logging plugin myself. If you have already used it, let us know how you liked it!
* Actually, debugging always changes application behavior in some way, but for our article, FirePHP gets it close enough. If you wanna go down that rabbit hole with me, buckle up, because it’s going to be rough ride.
** That’s a lot of fires to keep track of. It’s easy to keep track of once you have everything installed and operating correctly.
† Checking for a hack: Look at localhost behavior, known clean; search the wp-hackers list for cron and scheduling; read through the WordPress plugin source code for more clues to normal behavior.
