/etc: FirePHP for Ajax Development

Firebug is without doubt the most popular development tool among Firefox plugins. Christoph Dorn thought it would be nice to have PHP integration for it.

by Christoph Dorn

The column describes why FirePHP is perfectly suited for Ajax Development and how to implement a selective logging system allowing the developer to switch on and off specific logging items on the fly. A complete working demo you can take and make your own is also included.

If you do not already have a php|architect subscription head on over to their site and purchase the November issue.

If you watched CNN’s coverage of the 2008 US Presidential Elections you will have seen their “New Toy”. An interactive touch display that takes presenting data to the next level. It is developed by Jeff Han of Perceptive Pixel.

It is great to see this technology appear in different mediums and not restricted to iPhones or Table Tops.

These days most computers have internet access. There is no reason why the content in presentations needs to be so static any more.

I think modern “presentations” will be much more fluid. There will be a primary sequence of points for the presentation but the presenter will be able to explore arguments by bringing up data, graphs, charts, photos, websites, screenshots, etc… completely interactively while staying completely engaged with the audience.

More importantly, you will be able to download the presentation later and view it again. You will be able to stop it at any point in time and interactively dig deeper into the data presented or look at the sources of the data to follow your own ideas.

When I went to the CNN website to check out the election section I was disappointed to see the data presented with basic flash objects on separate pages. It would have been nice to see the same “presentation” as was on the touch screen on TV.

There is still some technology missing to make interactive presentations the norm, like hand gesture capturing to control projected screens in lecture theaters but it won’t be long. In fact, there is probably already stuff out there that can already do all this. Let’s see it!

I am looking forward to the day when presentations are not controlled by powerpoint slides but rather follow the presenter’s experienced judgement of where the audience needs to be taken.

The release includes 27 bug fixes and feature enhancements. The scope of this release was primarily focused on improving the current feature set in terms of usability, reliability and support for logging complex objects. You can find the changelog here.

After installing the FirePHP 0.2 extension you will be directed to the Install page after your next Firefox restart. On this page you need to download the updated FirePHPCore library. Next you can visit the Learn page for information on how to get started with FirePHP. Finally refer to the Usage page as a reference for all supported features.

I want to thank everyone who has participated in the Community Forum and Issue Tracker to report, test and resolve issues. Your help has been invaluable to make this release possible.

Finally, I have a new Contribution page that includes a Donation button. If FirePHP saves you time I encourage you to donate what you believe is reasonable. It will allow me to spend more time maintaining FirePHP and make improvements that are suggested.

The 0.2 release includes the following improvements. See the Usage page for more information.

Enhanced object logging

FirePHP will now log and display non-static private and protected object members. If they are declared static they can be logged with PHP 5.3. The variable viewer will indicate the visibility with a little icon. Red is private, orange is protected and green is public. Grey means undeclared (you have assigned a value but not declared the variable in the class) and the square means it is static.

Logging complex objects containing cyclical references to many other objects is no longer a problem. By using options you can now specify the mximum depth to traverse objects and arrays. You can also exclude specific object members from being logged in order to remove infomation that is not required and will only slow down your debugging.

File and Line Information

By default you can see the source file name and line number where each message was triggered when you hover over the message in the Firebug Console.

Full UTF-8 and Latin-1 Support

FirePHP now supports UTF-8 and Latin-1 (ISO-8859-1) encoded files and strings. All other encodings should work as well as all data gets converted to UTF-8.

Enhanced Variable display in Console

The variable display in the Console has been completely overhauled. Different types of variables including objects and labels are now properly displayed, abbreviated and highlighted.

Other Improvements

• The Variable Viewer can be resized
• FirePHP will tell you when you need to upgrade your server library
• Built-in error and exception handlers
• Message grouping
• New object oriented API to access FirePHP via static methods
• Support for Firebug 1.3

He explains how to use Zend_Db_Profiler to analyze all SQL queries on a page and how to improve the performance of the queries by adding indexes.

Here is a quick modification to his example that will send the profiling information to firebug instead of printing it to the page.

To use Firebug all you need to do is use Zend_Db_Profiler_Firebug as the profiler instead of the default one.

$profiler = new Zend_Db_Profiler_Firebug('All DB Queries');
$profiler->setEnabled(true);
 
$params = array(
    'host' => 'localhost',
    'username' => 'dbusername',
    'password' => 'dbpassword',
    'dbname' => 'dbname',
    'profiler' => $profiler
);
 
$db = Zend_Db::factory('PDO_MYSQL', $params);

You can skip the whole second step of printing the profiling information to the page.

This code is assuming you are using Zend_Controller_Front and executing your queries in your model, view or controller files. For other use-cases see here.

Now open your Firefox web browser with Firebug and FirePHP installed and open the page you want to profile.

When you view the Firebug console you should see something like this:

What if you could just think “I wonder what my stats are today?” and your Mac would tap into your mind and give you the answer. It’s probably a good thing it has not advanced that far yet.

But what if you could ask your Mac and it would answer?

Well … It can! The needed speech tools are built right into Mac OS X.

By default, once enabled, you can voice-control some common features of most applications. You can also open Terminal and type:

say You look good today

These are two separate systems (speech recognition and speech synthesis). To have your Mac listen for some keyword and then answer with some intelligent information you need some plumbing code. Luckily it’s not hard to do at all and there are only a few steps. I’ll walk you through the setup.

Requirements

• Mac OS X Tiger but it should work just as well on Leopard
• PHP5
• A text editor
• I am also assuming you have Growl installed

Step 1:  Save and configure PHP script

Save the PHP script below in a file somewhere on your hard drive. You will need to know the absolute path to it. Lets say you save it as FeedBurnerStats.php in your user home directory. My path would be /Users/cadorn/FeedBurnerStats.php

Once saved you need to edit it to change the <username>, <password> and <feeduri> configuration options. That is your FeedBurner username and password as well as the unique URI of your feed that FeedBurner gives you. Your login information will be encrypted before it is sent so don’t worry about that.

If you have Growl installed this script will also show your stats in Growl. If you don’t, just set $growlnotify to false.

I am not going to run you through the code. It should be simple enough to follow. If you don’t know PHP don’t worry. This will still work for you.

<?php
/*******************************/
// Your account username
$user = '<username>';
// Your account password
$pass = '<password>';
// The URI of your feed (http://feeds.feedburner.com/<feeduri>)
$feedUri = '<feeduri>';
// Path to growlnotify if you want growl notifications
$growlnotify = '/usr/local/bin/growlnotify';
/*******************************/
 
$url = 'https://api.feedburner.com/awareness/1.0/GetFeedData?uri='
       . $feedUri;
 
$options = array(
    'http'=>array(
        'method'=>'GET',
        'header'=>'Authorization: Basic '
                  . base64_encode($user . ':' . $pass) . "\n"));
 
exec('say Fetching');
 
$xml = file_get_contents($url, false, stream_context_create($options));
 
$tree = simplexml_load_string($xml);
 
$msg = $tree->feed->entry[0]['circulation']
       . ' Subscribers and ' . $tree->feed->entry[0]['hits'] . ' Hits';
 
if ($growlnotify) exec($growlnotify . ' -m "' . $msg . '"');
exec('say ' . $msg);
?>

Step 2: Choose your speech synthesis voice

Go to your System Preferences and click on Speech under the System group. Select the Text to Speech tab and choose a voice in the System Voice dropdown. I like Vicki. She seems to be the clearest.

Step 3: Enable speech recognition

Click on the Speech Recognition tab. Ensure Speakable Items is set to On. You should now see this little tool: Now check your Settings. I am using my internal microphone and have it set to continuously listen without needing a keyword before a command is spoken. Turn the command acknowledgement off as it will interfere. Before we continue, ensure that the system is actually listening. Toggle your Listen Key until the bars (blue and green) in the speech tool move as you speak.

Step 4: Install your “statts” voice command

Click on the Commands tab and ensure Application Specific Items is checked. Click on Open Speakable Items Folder. In the Finder select the Application Speakable Items folder and select an application to enable the command for. It has to be attached to an application for it to work. I have mine in firefox-bin as I use Firefox all day. Leave this folder open in your Finder and proceed below.

Save the following script into a file called statts.scpt on your desktop. Double-click the file you just created. It should launch the Script Editor.

tell application "Terminal"
	do shell script "/usr/bin/php /Users/cadorn/FeedBurnerStats.php"
end tell

Edit the path to PHP if it is different and update the path to your PHP script file we saved above. To find the absolute path to your PHP binary you can type which php in your Terminal window. Remember that this needs to be the PHP5 binary.

Go to the File menu and select Save As …

Now drag the folder you have selected in the Finder (see above) onto the Where dropdown in the Save As dialog. Save the script. It will be automatically compiled.

My file would now be at /Users/cadorn/Library/Speech/Speakable Items/Application Speakable Items/firefox-bin/statts.scpt.

NOTE: The name of the file is important. It will be your voice command. The double tt is not a mistake. The command needs to be written as it sounds.

At your command

Open the application you have enabled the command for and speak it out aloud. When the system recognizes your command it will show briefly above the speech tool and execute your script.

The script will say fetching, then get your stats via the FeedBurner Awareness API and tell you the number of subscribers and hits for the past 24 hours.

The statts word is pretty forgiving so you should not have too much of a problem having the system recognize you. If it is not working you can go to the Speech Recognition tab and under Settings try and calibrate your system. If it is recognizing other commands then you probably have an error in your Speakable Item Script or the PHP script.

While playing with this I noticed that the system does not recognize changes to the Speakable Item Script right away. It seems to index it every 10 seconds or so.

Now Innovate

This example may not be the most useful to you. The point is you now know how to trigger a PHP script via a voice command as well as have a PHP script talk to you.

Change the code, make it more useful. Have some fun with it. Who knows what you can come up with.

If you need a function to have the highest performance, try to express it non-recursively. It can make a 500% difference.

Now I thought the 500% speed gain (and associated fewer CPU cycles) was a number he grabbed out of the air or it was based on comparisons with the previous Set::extract() method and very specific to that case. It surely would not apply to any algorithm in general as some are much more complex than others.

While it may not apply to any algorithm in general it may apply to similar algorithms. So I benchmarked the new Set::extract() against a library I remembered called JSONPath (code) which also allows you to extract data from nested arrays using a string selector. JSONPath uses recursion just like the old Set::extract() method.

I used the second $users array from here and ran the following two tests:

// Simple
Set::extract('/User/name', $users);
jsonPath($users, "$..User.name");
 
// Complex
Set::extract('/User/Item[id>2]/name', $users);
jsonPath($users, "$..User.Item.[?(@['id']>2)].name");

Both of these tests generate the same output so they are a pretty good comparison for the underlying algorithms. Running them 100 times each gives the following result:

Lo and behold! The speed difference is ~500%!

Now that is a funny answer to my question! NOTE: The two libraries (and old Set::extract()) have different features and cannot be compared like this. The 500% is only applicable for this specific example but take it to show that recursion should definitely be evaluated when looking for speed gain. The cost for less recursion may be less modularity and extensibility, but that is a tradeoff you always need to make.

Now don’t use these figures to choose between Set::extract() and JSONPath. They work very differently internally. JSONPath uses a lot of recursion and jumping around but it also uses a lot of regular expression matching which is notoriously slow in PHP.

JSONPath has a very academic background and illustrates some neat concepts. If someone was to take it and put a practical spin on it with some performance improvements (reducing recursiveness!?) and new features, it could make for an even better library to extract data from arrays.

This post is about the variable substitution and variable formatter functionality in domplate. I will start by showing you what you can do with the domplate implementation that is shipped with Firebug and then tell you about a little enhancement I made on my own copy.

Lets take a look at the following template taken from here. To run this locally you will also need this copy of domplate.

TABLE(
  TBODY(
    TR(
      TH({'style':'background-color: gray;'},
         'Names')
    ),
    FOR('row','$people|getRows',
      TR(
        TD({'style':'background-color: $row.color'},
           'Hello $row.name|formatName')
      )
    )
  )
)

As you can see, a domplate template is simply a set of nested function calls where the function name represents the HTML tag except for some special functions like FOR. The first argument contains any HTML attributes you want to add and the remaining arguments further tags or the actual content that is to reside within the tag.

Variables

You will notice that there are a number of variables in the basic form of $var. Variables in domplate work just like they do in javascript although only printing of object variables is supported. Arrays are supported for passing data to formatters (more on that later), but they cannot be printed as the array items cannot be accessed directly.

Variables have scope. When a template executes all variables passed to domplate from your calling code will be present by default throughout the entire template. In the example above the FOR loop will create its own sub-scope with its own variables. These variables are only accessible from within the FOR loop and are not available after the for loop as exited.

You can access properties of objects stored in the variables via the dot syntax. The $row.name variable accesses the name property of the row object.

A variable is recognized as such if it begins with a $ and ends with a space, comma or pipe (more on the comma and pipe later). The first character after the $ may not be numeric (just like in javascript) and any alphanumeric characters including underscore and period and valid thereafter.

$var1
$var1.prop1
$var1 Hello
Hello$var1

You can print any number of variables embedded into the tag content.

Variable Formatters

Variables are great and essential in a template system, but domplate really shines in its support for variable formatters. A variable formatter is a function callback that allows you to call a function defined within your template object and pass along a template variable. The task of the function is to format the variable and return it to be printed, used in special functions like FOR or piped to another formatter.

To define a formatter simply append |func to the end of a variable. This will pipe the variable to the function called func which means that it will pass the variable to the function as the first and only argument.

In the above example $row.name|formatName will pass the $row.name variable to the formatName function and the result will be printed inline. Similarly $people|getRows will pass the $people variable to the getRows function and the result will be used to iterate over in the FOR loop.

You can chain multiple formatters to a variable by appending more than one |func to it. It will pass the specified variable to the first function and the result to the second function and so on. Think of it like unix pipes. Hence the use of the | character. You can pipe the result of one formatter to another.

$var|func
$var|func1|func2

The FOR loop

While we are at it lets examine the FOR loop a bit closer. I will have further posts about other built-in functions in future.

The FOR function is a built-in template function that iterates over a list of values by repeating its sub-template for every entry in an indexed array. Each array value can be a simple string, integer or an object containing one or more properties where a property can contain further nested objects.

FOR('row','$people|getRows',
  ...
)

This FOR loop will iterate over the array returned by the getRows formatter. The formatter in turn is taking in the $people variable as its source of data. This setup allows you to iterate over any variable as long as the formatter knows how to interpret it in order to return a list of values to the FOR loop.

As the loop steps through the array, each value is assigned to a variable called row. You can access it via $row and if your array values are objects you can use the dot syntax to get the object properties such as $row.name. As mentioned above the $row variable has limited scope and is only available from within the loop.

You can nest FOR loops and supply a variable without a formatter as the data for the loop as long as it is already an indexed array of values.

Passing multiple variables to a formatter

If you use formatters in their basic form which is to format variables for display you will usually only need to pass one variable to it. Even if you need to be able to customize a formatter dynamically you can register a variable on the template object which the formatter can access.

There are cases however where you don’t want to pollute the template object with such variables or you need more flexibility in your templates especially if they are nested and/or inherit and customize other templates. It is also useful if you need to combine two variables in a formatter that will be used to feed a FOR loop.

This is where my little enhancement comes in handy.

$var1,$var2|func
$var1,$var2,$var3|func1|func2

It allows you to pass two or more variables to a formatter while still being able to chain formatters. Simply separate each variable with a comma to assemble a list of variables to be piped to the first formatter as function arguments in corresponding order.

function func(var1,var2) {
}

Do not include any spaces in this list or the variables will be treated separately. The second formatter will simply receive the result of the first as its only argument.

Note that this feature is only available in my copy of domplate and not supported by Firebug at this point. You can see an example of it here. You need to download it along with the domplate code to run it.

Enjoy! If you have any questions post them here.

As part of my domplate project that is aimed at making the template system available for general use in the browser (and yes there will be documentation) I have begun by adding some debug logging capabilities.

I find logging more useful for understanding intircate and highly nested code as opposed to interactive debugging as you can see the entire execution path on one page. Turns out that firebug is ideally suited for this task thanks to its logging console that supports nested groups.

If you work with domplate you will want to try out this modified version with the added logging capabilities. There is no logging levels yet and it spits out A LOT of information so it can be a bit slow but it will give you a great overview of what happens behind the scenes including the generated dynamic code.

To use it simply enable DomplateDebug logging and make sure your Firebug console is enabled:

DomplateDebug.enabled = true;

There is a page with a simple demo here. You will need to download it. At the moment domplate only works on Firefox.

While I was building the logging system I was on the hunt for a problem reported by Nathan. (The demo page above is a slightly modified version of his testing code that showed the problem). The logger allowed me to narrow it down and solve it.

It turns out to be so trivial, yet it was so hard to track down and figure out. Are you ready?

When you define tables in your templates you must include a TBODY tag!

TABLE({border:1},
  TBODY(
    TR(
      TH({colspan:2},'array')
    ),
    FOR('x','$value',
      TR(
        TD('$x.name'),
        TD(
          TAG('$x.val|format',{value:'$x.val|parseParts'})
        )
      )
    )
  )
)

Now don’t feel too bad if you have made this mistake yourself. The tbody tag after all is optional when coding websites, but evidently it is NOT optional in domplate.

Stay tuned for more domplate magic on my blog.

This means that if you use Zend Framework (ZF) you can now log to your Firebug Console via FirePHP without needing to download any other PHP files such as the FirePHPCore library.

There are two primary components available at this time. One is the Zend_Log_Writer_Firebug and the other the Zend_Db_Profiler_Firebug.

Lets check out how to use these new components. I would think that most ZF applications use Zend_Controller_Front so the following examples assume you have a basic MVC application.

Install Firebug and FirePHP

You first need to install the Firebug and FirePHP Firefox extensions. You can install them from here:

• Firebug: https://addons.mozilla.org/en-US/firefox/addon/1843
• FirePHP: https://addons.mozilla.org/en-US/firefox/addon/6149

Logging to FirePHP with Zend_Log

All logging in ZF is done via Zend_Log which delegates the actual logging to registered log writers. The Zend_Log_Writer_Firebug component is such a writer and as the name indicates it sends your log data to Firebug.

Place the following code in your bootstrap file somewhere before dispatching your front controller:

$logger = new Zend_Log();
$writer = new Zend_Log_Writer_Firebug();
$logger->addWriter($writer);

To keep an instance of your logger you can use:

Zend_Registry::set('logger',$logger);

The Firebug log writer is all setup and ready to go. You can now dispatch your front controller and log data from within any of your model, view and controller files with the following:

$logger = Zend_Registry::get('logger');
$logger->log('This is a log message!', Zend_Log::INFO);

If you have done everything correctly you should see “This is a log message!” in your Firebug Console. If it is not showing up, make sure you have the Net and Console Firebug panels enabled.

The Zend_Log::INFO constant passed to log() determines the priority of the logging message. To increase the priority you can use Zend_Log::WARN or Zend_Log::ALERT for example which will produce a log message with a warning and error style respectively.

To log a plain message without any icon in Firebug you can use Zend_Log::DEBUG.

While logging simple strings is fun, FirePHP really comes into its own when logging complex data structures such as multi-dimensional arrays and objects. All you need to do is pass the object you want to log to the log() method, specify the logging priority and FirePHP will render the data appropriately.

For example you can log your exceptions with a complete expandable stack trace with the following code:

try {
    // Code that may throw an exception
} catch(Exception $e) {
    Zend_Registry::get('logger')->err($e)
}

Note the above code also uses the err() shortcut instead of passing the Zend_Log::Err constant to log().

For extensive documentation on how to use the Firebug log writer including information on how to create tables in the Firebug Console please see the online documentation.

Profiling Database Queries

There are numerous reasons for wanting to see a list of database queries executed during a page request. The Zend_Db_Profiler_Firebug component makes this possible and displays the result in an expandable table in the Firebug Console.

Place the following code in your bootstrap file somewhere after your database adapter ($db) is initialized and before dispatching your front controller:

$profiler = new Zend_Db_Profiler_Firebug('All DB Queries');
$profiler->setEnabled(true);
$db->setProfiler($profiler);

That’s it! Any database queries executed in your model, view and controller files will now be sent to Firebug along with the time it took to execute each, the query that was executed and any parameters bound to the query.

For a more detailed tutorial on how to use Zend_Db_Proflier_Firebug see here.

Try it Out!

You may be used to debugging your ZF code using Zend_Debug::dump() or even var_dump(). What do you have to loose trying these new components? They offer the big advantage of not dumping your debug data to the page. They allow you to debug applications with intricate designs as well as AJAX request that require clean JSON or XML responses.

Even if you are used to xDebug, FirePHP may prove to be a faster debugging solution in some cases than starting a debug session every time you need to ge some quick feedback as to what your variables are doing.

If you get tired of typing Zend_Registry::get(’logger’)->debug(); every time you need to print some debug data you can place the following wrapper function in your bootstrap file:

function fb($message, $label=null)
{
    if ($label!=null) {
        $message = array($label,$message);
    }
    Zend_Registry::get('logger')->debug($message);
}

Now you can simply use:

fb('This is a log message!');
fb($_SERVER, 'Server Variables');

One last note of caution. Do not log your debug data for everyone to see! Make sure you disable all logging when your application runs in production. Instead of removing your logging code every time you upload your application, you can disable the log writer and database profiler in your bootstrap file with:

$writer->setEnabled(false);
$profiler->setEnabled(false);

More Information/Help

For detailed information on these two components please refer to the Zend Framework Manual. Specifically the Zend_Log_Writer_Firebug and Zend_Db_Profiler_Firebug chapters.

If you need help use one of the following forums:

• Zend Framework Mailing Lists (Use the General List)
• FirePHP Community Forum

I find it great for inherited websites where I need to troubleshoot problems on live servers, as I can have all the debug/variable dump/etc crap dump to the FirePHP console so it doesn’t show up on the website while I’m trying to track down a problem and the budget is not there to make a dev copy of the system[they need an in and out fix, 4 hours tops]

It illustrates a great use case. Many times you need to maintain legacy code that you don’t have a development environment for. FirePHP enables you to do ad-hock debugging on a live site without affecting site visitors as long as you are careful not to cause any parser errors. Maybe not a great idea on a high-traffic site, but chances are if the site runs on more than one server or has a lot of traffic the owners will be able to afford a development environment for you.

It may also be a great tool for helping you convert PHP4 applications to PHP5.