Debugging PHP applications has always been a bit of a challenge, as the environment is so distributed. At the minimum, there is a web server, the PHP interpreter, and the web browser. While there are tools that add debugging environments to PHP (such as XDebug), you don’t always have access to install them on the server you’re working with.

Fortunately, you can gain some reasonable debugging capabilities through FirePHP. When you want to dump objects or variables back to your browser without having to do so in your HTML, FirePHP is ready for the task. It can also be used to handle code traces and PHP errors.

FirePHP is both a Firebug extension and a PHP library. When the PHP library is in place, special HTTP headers containing JSON objects are created. Firebug reads the HTTP headers, decodes the JSON, then shows the variables in the console. Since the output body is unaffected, it is extremely useful for debugging XML, JSON, PDFs, images, or other non-HTML output generated in PHP.

How can I use FirePHP in Joomla?

FirePHP is designed as a PEAR package you can install and then include in any of your PHP projects. However, you may not always have shell access to the server you’re working on, let alone have the ability to install packages via PEAR. Even if you are able to install FirePHP via PEAR, you still have to find a way of including FirePHP throughout Joomla. You could put the includes for FirePHP at the top of your extension’s PHP file, but then it won’t be available elsewhere. You could also modify the root index.php file to include it, but this forces you to hack core code.

Fortunately, FirePHP can be installed and used on any Joomla site through a System plugin. In typical Joomla fashion, there are now multiple FirePHP extensions available. First, there’s the FirePHP System Plugin. This one is extremely straightforward: install the FirePHP plugin, enable it, then use FirePHP anywhere in your Joomla code. EDIT 5/4/10: the FirePHP System Plugin is no longer available.

While the FirePHP System Plugin is stable and works the way you would expect, there’s another plugin named JFirePHP with much more to offer. The plugin parameters configure core FirePHP functionality, as well as a few extra Joomla-specific features.

When using JFirePHP for the first time, there are a couple of parameters you will want to change right away. By default, JFirePHP is set to only run when Joomla’s Debug Mode is turned On. While this is a very safe way of making sure that you don’t start spewing FirePHP headers on a live site by accident, it’s not so helpful when you have a development site with Debug Mode off. Set Limit functionality to Joomla debug mode to No and FirePHP will be loaded with each request.

The other option to change is Verbose Output. When this is enabled, each HTTP request will result in at least one message in the Firebug console. This message will have a summary of the FirePHP settings, as well as the current PHP error reporting configuration. When you have both of these parameters set, it should look like this:

Installing FirePHP on the client side

FirePHP works as two pieces of software: there’s the PHP library on your sever, then the FirePHP extension that works with Firebug in Firefox. If you don’t already have Firebug, you can get it at https://getfirebug.com. Once Firebug is installed, also grab a copy of the the FirePHP extension. Before you can use FirePHP, you’ll need to enable it for the domain where your site is located. When you pull up the Firebug console, you’ll notice two “bug” icons on the left: one is brown and one is blue. The blue one is for FirePHP. Click this, select Allowed Sites…, then add the domain where you’ll be using FirePHP. Adding sites manually ensures that arbitrary sites cannot hijack your Firebug console. EDIT 2/23/10: Christoph Dorn has informed me that this feature is currently non-functional. There is no need to add your site to the list.

With this in place, the FirePHP extension is ready to decode the special HTTP headers being sent from the server side. If you have JFirePHP installed and Verbose Output set to Yes, you should now see messages in your FireBug console for every HTTP request you make to Joomla:

Sending messages to the console

While the Verbose Output option will give you some basic information about PHP error reporting, you will also want to be able to output other messages and variables. The easiest way to do this is to call fb(), passing in the message or variable you want to send to the console. The following component runs fb() and passes in a short message:

<?php
defined( '_JEXEC' ) or die;

fb('hello console');

This is enough to let us know that FirePHP is running, Firebug is interpreting the HTTP headers correctly, and the fb() function is working. However, it’s usually much more useful to be able to inspect a variable within our program. The fb() function will accept an object, array, or any other PHP variable and send it along in the HTTP headers. In this example, we’re making a database query, then sending the results back to the console:

<?php
defined( '_JEXEC' ) or die;

$database =& JFactory::getDBO();
$database->setQuery("SELECT * FROM #__content WHERE id = 1");
$rows = $database->loadObjectList();

fb($rows);

While the first few columns of the first record are displayed, the rest is truncated so the console isn’t overwhelmed by the result array. When you mouse over the console message and click, it pops up a separate window where the data is seen in full:

Labeling your variables

So far, we’ve only sent one or two messages to the console at a time. However, there are situations where using FirePHP to debug a loop is helpful. The sample component is modified below to get several records out of a larger dataset, then loop over the results, sending each row to the console:

<?php
defined( '_JEXEC' ) or die;

$database =& JFactory::getDBO();
$database->setQuery("SELECT * FROM #__modules");
$rows = $database->loadObjectList();

foreach ($rows as $row) {
    fb($row);
}

This will quickly get confusing, especially when fb() is called from other portions of the codebase. To sort out the different variables being sent to the console, another argument is passed into fb(), prefixing each with a label. The modified foreach() loop looks like this:

foreach ($rows as $row) {
    fb($row, 'Module: ' . $row->title);
}

Redirecting errors to the Console

Modern JavaScript code frequently makes several HTTP requests to get data in XML or JSON format from server-side PHP. In this scenario, it is easy to miss notices and warnings coming from PHP even when display_errors in php.ini is set to on. Fortunately, the Redirect PHP Errors, Warnings and Notices option in JFirePHP will draw attention to these right away. With this option turned on, any error, notice, or warning will be sent to the console and PHP will halt for the request. The following component will throw a warning when the foreach() statement is reached:

<?php
defined( '_JEXEC' ) or die;

$not_array = 'orange';

foreach ($not_array as $value) {
    echo $value;
}

The Firebug console now reports the warning, along with the filename and line number where it occurred:

While this example didn’t include JavaScript, the same principle applies: JFirePHP will intercept all errors, warnings, and notices, then send them to the console and stop the PHP interpreter. Getting error messages and warnings in the console draws attention to bugs early on, especially when additional data is being pulled from Joomla asynchronously.

Scratching the surface

This is a limited subset of the functionality available through FirePHP. For more information, visit https://www.firephp.org/HQ/Use.htm. This reference has everything needed for using FirePHP to its greatest debugging capabilities. Since JFirePHP includes FirePHP automatically, omit the require_once statements seen in the examples.

With JFirePHP, you’re able to install FirePHP on your site, then turn it on or off at will. This is wonderful, as it can be left on during development, then switched off on the live site. It’s also possible to install the plugin solely on the development site, further avoiding security concerns. Regardless of how you use it, JFirePHP is a welcome addition to the arsenal of any Joomla developer’s toolkit.