The FirePHP Extension now (0.6) works again with Firebug 1.8: http://www.firephp.org/HQ/FinalRelease.htm (will appear on mozilla add-ons once approved)

What Happened?

I have been working on FirePHP 1.0 (comparison) for a few years now to come up with a streamlined way to develop PHP (and other languages) code in the modern web environment. To make this a reality a new server library and client is needed. I wrote both of these from scratch based on a bunch of research utilizing the latest technologies (especially for the client).

What sets the FirePHP 1.0 (server library) apart is that it includes a new cross language intelligence system called Insight intended to bring the FirePHP way of debugging to other programming languages. Furthermore Insight is designed to support multiple clients that can embed the Insight system (composed of CommonJS modules) in order to bring native support to IDEs and other developer tools (this aspect is not ready yet but will receive significant attention in time).

I wrote the new client (DeveloperCompanion) to support all existing FirePHP Extension features plus new ones (to be released with Firebug 1.9) free of charge. The paid version builds on the free foundation by offering more streamlined and time-saving features.

The arrival of Firebug 1.8 brings along a bunch of internal changes which broke the FirePHP Extension 0.5 release. Given that DeveloperCompanion is sufficiently ready I decided not not fix the FirePHP Extension and thought I would upgrade users to DeveloperCompanion to ensure everyone can keep using FirePHP with Firebug 1.8.

Feedback from users

Then I started receiving feedback about this decision. Users were not happy that they were now required to install a commercial extension. I did not think that this would be a problem. In my view the free features DeveloperCompanion offers are superior to the ones offered by the FirePHP Extension (if you don’t think they are let me know so we can make it so) and since 2007 I have received only one patch for the FirePHP Extension. I thought users would not object to a closed-source extension for a while until FireConsole is ready.

There seem to be two groups of FirePHP users. One is looking for and needs the new features that FirePHP 1.0 brings and the other is happy with the simple approach of the FirePHPCore library and insist on the entire stack being open source at all times.

Go forward

I have decided to continue to maintain the FirePHP Extension but it will not be upgraded to be compatible with the new FirePHP 1.0 Insight features. That means the FirePHP Extension will continue to support the FirePHPCore library only and implementations written to be protocol compatible such as the native Zend Framework implementation.

Users who want to use the FirePHP 1.0 Insight features with an open source extension will need to wait for FireConsole. Anyone who does not object to installing a free closed-source client can use the new FirePHP 1.0 Insight features today with DeveloperCompanion.

Finally, anyone looking for features that will streamline their PHP and JavaScript development workflow and toolchain can license DeveloperCompanion and as a result support the further development of FirePHP, Insight and related technologies. I know we all love open source but producing open source software still takes time and money. I appreciate your support.

I trust that this will satisfy everyone’s needs. If not, please let me know.

Launching Zend Server Instance on EC2

Go to http://www.zend.com/en/products/server/amazon/ and follow the steps to launch an instance.

NOTE: The Zend Server instances launched this way are billed to you on an hourly basis at a rate set by Zend.

The instructions below should work for any Zend Server or Free Zend Server Community Edition installation. The assumption is you are working with a new PHP 5.2+ Zend Server install. If you already have sites provisioned you can adapt the instructions to fit your needs.

Install & Download

Requirements

• Firefox 3.6
• Firebug 1.5+

Install the FirePHP Companion client extension:

Download the FirePHP 1.0 server library

Upload

SSH into the server and upload the phar archive you just downloaded to /usr/local/zend/share/firephp/firephp.phar (you will need to create the firephp folder).

Configure

We are going to configure FirePHP on a virtual host basis. Since we are working with a new server install that already has a default virtual host configured we are simply going to enable FirePHP for it.

Place the following just before the closing VirtualHost tag in the /etc/apache2/sites-available/default file:

SetEnv INSIGHT_CONFIG_PATH /var/www/package.json,/usr/local/zend/etc/firephp/credentials.json
php_value auto_prepend_file phar:///usr/local/zend/share/firephp/firephp.phar/FirePHP/Init.php

Restart Apache using the Zend Server Administration Interface by clicking on Restart PHP in the footer.

NOTE: You can use the same credentials.json file for all virtual hosts or refer to specific credentials files as needed.

Create a credentials file for FirePHP at /usr/local/zend/etc/firephp/credentials.json (you will need to create the firephp folder) with the following content:

{
  "cadorn.org/insight/@meta/config/0": {
    "allow": {
      "ips": [
        "your-ip"
      ],
      "authkeys": [
        "your-authkey"
      ]
    }
  }
}

NOTE: Make sure to update the your-ip value to your IP which you can get by visiting myip.cadorn.net. Keep the your-authkey value until you get your own below.

Finally we need to configure the site/application provisioned at /var/www. The changes we make here should be made in the application source code (that will be deployed to the virtual host) and reside in source version control together with the rest of the application. This will ensure FirePHP will automatically start working for the application if provisioned on any server with FirePHP pre-configured.

Create a file at /var/www/package.json with the following content:

{
  "uid": "firephp-test.zendserver.aws.firephp.org",
  "implements": {
    "cadorn.org/insight/@meta/config/0": {
      "cache": {
        "path": "/usr/local/zend/tmp"
      },
      "server": {
        "path": "/index.php"
      },
      "paths": {
        "./": "allow"
      }
    }
  }
}

NOTE: Make sure to update the uid property to a URI unique to your application. See here for more information on the uid property and other configuration options.

The default virtual host does not include a PHP file we can use for testing so we create one at /var/www/index.php with the following content:

<?php
echo 'Hello World from Zend Server + FirePHP';

We are now ready to authorize the client and log some test messages.

Authorize Client

In Firefox, open Firebug, enable the Console, Net and Insight panels and select the Console panel.

Load the index.php page (e.g. http://ec2-xxx.compute-1.amazonaws.com/index.php) and look for the Authorization Key logged to the Firebug Console.

Update the your-authkey value in the credentials.json file above to the Authorization Key copied from the Firebug Console. To keep track of which key belongs to whom you can set it as follows (notice the comment after the key):

{ "cadorn.org/insight/@meta/config/0": { "allow": {
      "authkeys": [
        "5312C15AF9D9C7610C8E33C854XXXXXX // user@ec2-xxx.compute-1.amazonaws.com"
      ]
} } }

NOTE: Each client will have a unique key for each hostname provisioned to access the application. This has nothing to do with the uid property in package.json which is used to identify the application itself irrespective of where it is deployed.

Test Debug Output

You can now place logging calls using the Insight API anywhere in the application and refresh your browser to see the result.

We are going to log a test message and information about the environment. Add the following to /var/www/index.php:

<?php
echo 'Hello World from Zend Server + FirePHP';
 
FirePHP::to('page')->console()->log('Hello World from FirePHP on Zend Server');
 
FirePHP::plugin('firephp')->recordEnvironment();

This tells FirePHP to log Hello World from FirePHP on Zend Server to the Firebug Console followed by information about the environment. For a complete API reference see here.

Troubleshooting

If you follow the instructions above you should not have any problems in getting FirePHP working on any Zend Server install.

The most common cause of problems are mistakes in the json configuration files. Any errors are logged to the PHP error log which you can access via the Zend Server Administration Interface.

If the error log does not help, the best place to start troubleshooting is by using the Test Tool. To launch go to the Insight panel in Firebug and click on the Test Tool button. Use the Server/Application Test by entering the URL to your index.php page.

The best place to get help if the Test Tool is not helping is here.

Future

This tutorial covered how to setup FirePHP and log a simple message on a Zend Server installation. FirePHP already has various features to make remote debugging like this useful and there is a lot more planned. More specifically the ability to browse and edit remote files right from within FirePHP Companion and much tighter Zend Server and Zend Framework integration. If this sounds like something that could be useful to you I encourage you to keep an eye out for new feature releases that will be announced on this blog.

Account Creation

Go to http://magenting.com/ and create an account. This tutorial was prepared by using a Spark account, but it should work just the same with all plans.

If you already have an account you can of course skip this step.

Install & Download

Requirements

• Firefox 3.6
• Firebug 1.5+

Install the FirePHP Companion client extension:

Download the FirePHP 1.0 server library

We use the FirePHP zip archive instead of the phar archive as including the phar archive does not seem to work on the Magenting hosting service.

Upload

Extract the FirePHP archive and locate the lib folder.

Log into the FTP account for the account created above and go into the /lib folder.

Upload all folders (excluding Zend – already exists on server). This will place all libraries required by FirePHP next to the ones used by Magento.

Configure

On the server (via FTP) create a file at /app/etc/package.json with the following content:

{
  "uid": "firephp-test.magenting.com",
  "implements": {
    "cadorn.org/insight/@meta/config/0": {
      "cache": {
        "path": "./../../var/cache"
      },
      "server": {
        "path": "/index.php"
      },
      "paths": {
        "./../../": "allow",
        "./credentials.json": "deny"
      }
    }
  }
}

NOTE: Make sure to update the uid property to the hostname assigned to you.

Create a second file at /app/etc/credentials.json with the following content:

{
  "cadorn.org/insight/@meta/config/0": {
    "allow": {
      "ips": [
        "your-ip"
      ],
      "authkeys": [
        "your-authkey"
      ]
    }
  }
}

NOTE: Make sure to update the your-ip value to your IP which you can get by visiting myip.cadorn.net. Keep the your-authkey value until you get your own below.

Bootstrap

To include FirePHP on the server replace the /index.php file with the following:

<?php
 
define('INSIGHT_CONFIG_PATH', __DIR__ . '/app/etc/package.json');
require_once(__DIR__ . '/lib/FirePHP/Init.php');
 
require_once(dirname(__DIR__) . '/codebase/magento-1.4.1.1/index.php');

NOTE: The Magenting service creates a link at /index.php which we are replacing with a file. At the time of writing the link pointed to ../codebase/magento-1.4.1.1/index.php. You may need to change the version if applicable by looking at the link before replacing it.

Authorize Client

In Firefox, open Firebug, enable the Console, Net and Insight panels and select the Console panel.

Load the Magento store (in my case http://firephp-test.magenting.com/) and look for the Authorization Key logged to the Firebug Console.

Update the your-authkey value in the credentials.json file above to the Authorization Key copied from the Firebug Console.

Test Debug Output

You can now place logging calls using the Insight API anywhere in the application and refresh your browser to see the result. For example you can log all DB queries by adding the following logging statement to /lib/Zend/Db/Adapter/Pdo/Abstract.php (that is on line 237 at the time of writing):

*** 232,239 ****
--- 232,241 ----
                      $bind[$newName] = $value;
                  }
              }
          }
+         
+         FirePHP::to('page')->console()->group('db', 'DB Queries')->log($sql);
 
          try {
              return parent::query($sql, $bind);
          } catch (PDOException $e) {

This tells FirePHP to log the $sql to a group called DB Queries in the Firebug Console. For a complete API reference see here.

Troubleshooting

If you follow the instructions above you should not have any problems in getting FirePHP working as long as the Magenting service does not make changes to its default structure.

The most common cause of problems are mistakes in the json configuration files. You can ask FirePHP to show these errors by setting the following constant before including FirePHP in /index.php.

define('INSIGHT_DEBUG', true);

Make sure to remove this again when you are done.

If this does not solve the problem the best place to start troubleshooting is by using the Test Tool. To launch go to the Insight panel in Firebug and click on the Test Tool button. Use the Server/Application Test by entering the URL to your store.

The best place to get help if the Test Tool is not helping is here.

Future

This tutorial covered how to setup FirePHP and log a simple message on the Magenting hosting service. FirePHP already has various features to make remote debugging like this useful and there is a lot more planned. More specifically the ability to browse and edit remote files right from within FirePHP Companion. If this sounds like something that could be useful to you I encourage you to keep an eye out for new feature releases that will be announced on this blog.

Get started with FirePHP 1.0 in 5 steps. Why upgrade? Check out the new features.

Requirements

• PHP 5.1+
• Firefox 3.6
• Firebug 1.5+

Step 1: Install FirePHP Companion

Step 2: Download FirePHP 1.0

Extract the archive and put the lib directory on your include path.

Step 3: Include in application

define('INSIGHT_IPS', '*');
define('INSIGHT_AUTHKEYS', 'client-auth-key');
define('INSIGHT_PATHS', dirname(__FILE__));
define('INSIGHT_SERVER_PATH', '/index.php');
require_once('FirePHP/Init.php');

This code must be included by every page on your site and is best placed at the top of your bootstrap file.

The INSIGHT_SERVER_PATH constant must point to any page that loads the code above.

Step 4: Authorize Client

Open Firebug, enable the Console, Net and Insight panels and select the Console panel.

Load a page from your application and look for the Authorization Key logged to the Firebug Console.

Update the INSIGHT_AUTHKEYS constant in your code with the Authorization Key copied from the Firebug Console.

Step 5: Log test message

Place the following into a page in your application:

$inspector = FirePHP::to('page');
$console = $inspector->console();
$console->log('Hello World');

Refresh the browser and look for Hello World in the Firebug Console.

Tips

• See upgrade.firephp.org if you are upgrading from a previous version of FirePHP.
• Update the INSIGHT_IPS constant to a comma separated list of allowed IP addresses to further tighten security. FirePHP will only announce itself to these IP addresses.
• Separate multiple keys by comma in the INSIGHT_AUTHKEYS constant.
• See Install for complete installation and configuration instructions.
• See Tutorials for a growing list of step-by-step guides.
• See API for the complete API reference.
• See FAQs for a growing list of frequently asked questions.
• See OpenSource to get support and contribute to FirePHP and related projects.

Notes

FirePHP 1.0 is still in BETA but quite functional and stable. All documentation will be released on the FirePHP website along with a complete redesign together with the first stable release.

FirePHP Firefox Extension 0.5.0

Install from: http://www.firephp.org/HQ/FinalRelease.htm

• Support for Firefox 4
• Support for Firebug 1.7
• Option to not change the User-Agent request header. In the Firefox menu go to: Tools -> FirePHP -> Options and uncheck Modify User-Agent Header. You must be using FirePHPCore 0.3.2+ or Zend Framework 1.10.3+.
• Option to show Variable Viewer on click (vs hover). In the Firefox menu go to: Tools -> FirePHP -> Options and check Click for Variable Viewer.
• More reliable logging when lots of messages are combined with groups

This release will go live on Mozilla Add-ons once it passes the review process.

FirePHPCore Server Library 0.3.2

Install from: http://www.firephp.org/HQ/FinalRelease.htm

• Workaround if getallheaders() does not exist
• Proper UTF8 encoding via mbstring if installed
• Support clients that set X-FirePHP-Version header instead of modifying User-Agent
• Fixes for PHP 5.1 compatibility
• Added maxDepth option
• Changed registerErrorHandler() to not throw by default to allow for multiple errors to be logged

This release is also available via the pear channel.

Zend Framework 1.11

Install from: http://framework.zend.com/

• (ZF-9346) Check for X-FirePHP-Version header in addition to User-Agent
• (ZF-10537) File & Line info is incorrect for FirePHP messages sent via Zend_Wildfire
• (ZF-10526) Zend_Controller_Request_Simple and Zend_Db_Profiler_Firebug

FirePHP 1.0 BETA

FirePHP 1.0 is coming along nicely and you can try out the beta at: http://upgrade.firephp.org/

It is pretty stable and quite functional and I encourage you to check it out. It will not take long before it goes live. I’ll be blogging much more about FirePHP 1.0 in the near future.

$someVariable = 'Some value';
 
// using FirePHPCore
$firephp = FirePHP::getInstance(true);
$firephp->log($someVariable);
 
// using Zend_Log_Writer_Firebug
$logger = new Zend_Log(new Zend_Log_Writer_Firebug());
$logger->log($someVariable, Zend_Log::DEBUG);

This works well for variables that contain small amounts of data. String, boolean and integer values are typically small and do not require much consideration. Array and object values may contain a lot more data as FirePHP traverses them (all array elements and object members) until the complete or maximum depth is reached. This is also true when logging exceptions and traces where all function and method arguments are also traversed. The data volume can quickly grow to megabytes which has fatal consequences for transmission of the debug data to the client and the client being able to render it.

FirePHP includes some solutions to these problem that you can take advantage of.

FirePHPCore

The FirePHPCore API includes a way to set the maximum traversal depth and allows for filtering of unwanted members on objects.

NOTE: These features are available as of FirePHPCore 0.3.2

$deepArray = array('A', array('very' => array('deep', array('array'))));
$deepObject = new DeepObject(); // contains member references to other objects
$mixedVariable = array('An', array('array that contains an object' => $deepObject));
 
// log arrays up to a maximum depth
$firephp->setOption('maxArrayDepth', 2);
$firephp->log($deepArray);
 
// log objects up to a maximum depth
$firephp->setOption('maxObjectDepth', 2);
$firephp->log($deepObject);
 
// when a variable is logged that contains arrays and objects in the graph
// the array and object depth is reset whenever a new type is encountered.
// use the following to set a maximum total depth
$firephp->setOption('maxDepth', 2);
$firephp->log($mixedVariable);

Rather than restricting the depth of an object logged you can also filter out certain class members. This is useful if there are certain members that are of no interest to you during debugging while you want to preserve others to full depth.

$firephp->setObjectFilter('DeepObject', array('MemberName'));
$firephp->setObjectFilter('DeepObject2', array('MemberName', 'AnotherMember'));

So when logging exceptions or traces you can use the following to significantly trim the volume of data.

$previousOptions =  $firephp->getOptions();
$firephp->setOption('maxDepth', 1);
 
$firephp->trace('Trace to here');
try {
    throw new Exception('Test Exception');
} catch(Exception $e) {
    $firephp->error($e);
}
 
// reset options to previous values
$firephp->setOptions($previousOptions);

Zend_Log_Writer_Firebug

Some of the same options are available with Zend_Log_Writer_Firebug even though they are not documented. Until documentation is available you can take a look at the source code for supported methods and options.

$firephp = Zend_Wildfire_Plugin_FirePhp::getInstance();
 
$firephp->setOption('maxObjectDepth', 2);
$firephp->setOption('maxArrayDepth', 2);
// NOTE: maxDepth is not supported at this time (ZF-10562)
 
// an additional option not supported by FirePHPCore which sets
// the maximum number of frames to include for traces and exceptions
$firephp->setOption('maxTraceDepth', 5);
 
// object member filtering
$firephp->setObjectFilter('DeepObject2', array('MemberName', 'AnotherMember'));

FirePHP 1.0

FirePHP 1.0 is in BETA and provides much more detailed control over how variables are traversed. You can upgrade to FirePHP 1.0 which is completely backwards compatible with the FirePHPCore library. Once you have verified that your existing code still works as before you can upgrade your your inclusion method and use the new Insight API.

// select the 'page' context and get the console (i.e. the Firebug Console)
$inspector = FirePHP::to('page');
$console = $inspector->console();
 
// override some options if applicable (defaults are shown)
$console = $console->options(array(
    'encoder.depthNoLimit' => false,
    'encoder.lengthNoLimit' => false,
    'encoder.maxDepth' => 5,
    'encoder.maxArrayDepth' => 3,
    'encoder.maxArrayLength' => 25,
    'encoder.maxObjectDepth' => 3,
    'encoder.maxObjectLength' => 25,
    'encoder.trace.maxLength' => -1,  // no maximum
    'encoder.exception.traceMaxLength' => -1  // no maximum
));
// the $console object now has the new options set
 
// class member filtering
$console = $console->filter(array(
    'classes' => array(
        '<ClassName>' => array('<MemberName>')
    )
));
// the $console object now also has the class member filter set
 
// log to the console
$console->log($mixedVariable');

For more information see the Insight API documentation or read up on FirePHP 1.0 here.

Summary

FirePHP is evolving into a complete debugging solution that must be flexible enough to cover all use cases. If you are using FirePHP and run into something that you believe it should handle please speak up. The FirePHP community will thank you for it.

You can follow FirePHP tips, news and happenings on twitter.

To start with I thought I would rework the example I included in my php|architect article. You will see how much easier it now is to accomplish the same, and with much less code, using FirePHP Companion instead of the existing FirePHP extension.

The Task

Let’s say you want to display an RSS feed on your site. You know that you should cache the feed on your server and only fetch updates from the origin server on a periodic basis. You know this because things get real slow if you don’t do that and you may get blocked from accessing the feed altogether if you call it with every request.

Knowing you need to build some caching logic it would be nice to have a tool that can help you see what is going on when you make a request to your script. You may want to know where your cache file is on disk, how stale it is, if the feed was re-fetched and the cache was updated and so on. This is exactly where FirePHP Companion comes in.

The Cumbersome Way

The technique I described in the php|architect article works, but admittedly is not the ideal solution as it is not necessarily that simple and requires a lot of framing code. To see what I mean you can take a look at the demo here and download the code here. Make sure you have the FirePHP extension installed to run the demo.

The FirePHP Companion Way

Now let’s look at how the same kind of problem is solved with FirePHP Companion. I am assuming you have a virtual host setup and working with FirePHP Companion. We only need two files and here they are:

index.php

<?php
/*i*/ // Denotes instructions used for insight that may be stripped out
 
// Bootstrap File
 
/* NOTE: You must have the FirePHP library on your include path */
 
/*i*/ define('INSIGHT_IPS', '*');
/*i*/ define('INSIGHT_AUTHKEYS', '<your-AUTHORIZATION_KEY>');
/*i*/ define('INSIGHT_PATHS', __DIR__);
/*i*/ define('INSIGHT_SERVER_PATH', './index.php');
 
/*i*/ require_once('FirePHP/Init.php');
 
/*i*/ FirePHP::plugin('firephp')->trapProblems();
/*i*/ FirePHP::plugin('firephp')->recordEnvironment(
/*i*/     FirePHP::to('request')->console('Environment')->on('Show Environment')
/*i*/ );
 
/*i*/ FirePHP::to('request')->console('Feed')->info('Startup');
 
// Application Code
 
require_once(__DIR__ . '/feed.php');
 
$feed = new Feed('http://www.phpdeveloper.org/feed');
 
$items = $feed->getItems();
 
if($feed->didLoad()) {
    echo '<p><b>Loading feed from: '.$feed->getUrl().'</b></p>'."\n";
}
 
foreach( $items as $item ) {
    echo '<p><a href="'.$item['link'].'">'.$item['title'].'</a></p>'."\n";
}
 
/*i*/ FirePHP::to('request')->console('Feed')->info('Shutdown');

feed.php

<?php
class Feed {
 
    /*i*/ private $console;
    private $url = false;
    private $ttl = 10;  // in seconds
    private $didLoad = false;
 
    public function __construct($url) {
        $this->url = $url;
        /*i*/ $this->console = FirePHP::to('request')->console('Feed')->on('Feed Debug');
    }
 
    public function getUrl() {
        return $this->url;
    }
 
    public function didLoad() {
        return $this->didLoad;
    }
 
    public function getItems() {
        $this->didLoad = false;
 
        $file = $this->getCachePath();
 
        /*i*/ $this->console->label('Cache File')->log($file);
        /*i*/ $this->console->label('Cache File Exists')->log(file_exists($file));
 
        if(file_exists($file)) {
            $fileTime = filemtime($file);
            $fileTtl = time()-$fileTime;
            /*i*/ $this->console->label('Cache Time Remaining')->log($this->ttl-$fileTtl);
        } else {
            $fileTime = false;
            $fileTtl = 0;
        }
 
        if($fileTtl >= $this->ttl
           /*i*/ || FirePHP::to('request')->console('Feed')->on('Force Reload Cache')->is(true)
          ) {
            /*i*/ $this->console->info('Deleting Cache File');
            if(file_exists($file)) {
                unlink($file);
            }
        }
 
        if(!file_exists($file)) {
            /*i*/ $group = $this->console->group()->open();
            /*i*/ $this->console->log('Load feed and store in cache file');
            $this->load();
            /*i*/ $group->close();
        /*i*/ } else {
        /*i*/     $this->console->info('Skip load as feed is cached');
        }
 
        $json = json_decode(file_get_contents($file), true);
 
        /*i*/ $this->console->label('Feed data')->log($json);
 
        return $json;
    }
 
    private function load() {
        $this->didLoad = true;
 
        $file = $this->getCachePath();
 
        /*i*/ $this->console->label('URL')->log($this->url);
 
        $startTime = microtime(true);
    	$content = utf8_encode(file_get_contents($this->url));
 
        /*i*/ $this->console->label('Load Time')->log(round(microtime(true)-$startTime,5));
        /*i*/ $this->console->label('Raw Feed Data')->log($content);
 
    	$xml = simplexml_load_string($content, 'SimpleXMLElement', LIBXML_NOCDATA);
    	if(!$xml) {
            /*i*/ $this->console->error('Error parsing XML data');
    	    throw new Exception('Error parsing XML data');
    	}
        /*i*/ $this->console->label('Parsed Feed XML')->log($xml);
 
    	$data = array();
    	foreach( $xml->channel->item as $item ) {
    	    $data[] = array(
    	        'title' => (string)$item->title,
    	        'link' => (string)$item->link
    	    );
        }
 
        /*i*/ $this->console->label('Final JSON Data')->log($data);
 
    	file_put_contents($file, json_encode($data));
 
        /*i*/ if(file_exists($file)) {
        /*i*/     $this->console->info('Saved cache file');
        /*i*/ } else {
        /*i*/     $this->console->error('Error writing to cache file');
        /*i*/ }
    }
 
    private function getCachePath() {
        return __DIR__ . '/cache.txt';
    }
}

Instead of providing a list of instructions on how to use FirePHP Companion with the code above I have put together a short screencast which I am hoping is much more convenient.

Summary

FirePHP Companion can help in understanding what is going on with your application. All you need to do is add logging calls in strategic places and hit refresh! Feel free to leave the code as is when you publish to production servers as the internal data will only be available to authorized clients. Things are optimized to keep overhead to a minimum for production requests on most applications.

There are still some features missing to make FirePHP Companion part of your daily workflow and that is where your feedback comes in. I encourage you to post your experience with FirePHP Companion on the mailing list and let me know what is missing for you.

After countless hours of research and development I am pleased to announce the first fruit of my labor.

FirePHP Companion is an alternative client for FirePHP that goes well beyond simple console logging and provides many features integral to an efficient development and debugging workflow.

I think this time around I am much closer to hitting the mark I was after to begin with and I hope you will judge my approach for yourself. FirePHP Companion is a commercial tool ($99 USD when released) with a free LITE version intended to replace the existing FirePHP Firefox Extension. Both editions use the same server library (FirePHP 1.0) and while the free version will focus on logging from server-side code to Firebug, the paid version will focus on providing a complete end-to-end development and debugging solution that seamlessly integrates with your existing applications.

Getting Started

Requirements:

• PHP 5.3+ (PHP 5.1+ if you use the zip archive)
• Firefox 3.6+
• Install Firebug: http://getfirebug.com/
• Install FirePHP Companion: http://www.christophdorn.com/Tools/
• Download FirePHP 1.0: http://reference.developercompanion.com/#/Tools/FirePHPCompanion/Install/

NOTE: The FirePHP 1.0 release will make it onto www.firephp.org later this year.

Let’s assume you are using the phar archive and you have the hostname http://demo.localhost/ mapped to a directory containing an index.php file and the phar archive.

define('INSIGHT_IPS', '*');
define('INSIGHT_AUTHKEYS', '');
define('INSIGHT_PATHS', __DIR__);
define('INSIGHT_SERVER_PATH', '/index.php');
require_once('phar://'.__DIR__.'/firephp.phar/FirePHP/Init.php');

When you integrate FirePHP into your application the code above should be place at the top of your bootstrap file to enable FirePHP for your entire application.

Once included you can start logging to FirePHP Companion:

$inspector = FirePHP::to('request');
$console = $inspector->console('Debug');
$console->log('Hello World');

This works by first selecting the request context and obtaining a named console called Debug and then logging to it. In FirePHP Companion this will be displayed as follows:

To see the messages you have logged follow these steps:

1. Using Firefox browse to http://demo.localhost/
2. Open Firebug and enable the Net panel
3. Refresh the page for the request to show up in the Net panel and expand it
4. Select the Insight tab
5. Set the INSIGHT_AUTHKEYS constant in index.php to the authorization key displayed
6. Refresh the page, expand the request in the Net panel and select the Insight tab again
7. Click Inspect with Companion which will load the Companion Window

Congratulations! You have logged your first message.

FirePHP Companion includes a comprehensive Reference that holds relevant documentation for all FirePHP features. To access the documentation launch the Companion Window (double-click in the Firefox status bar) and click on the Reference button in the footer. Once loaded click on the Tools section on the left.

You can also access the Reference here: http://reference.developercompanion.com/

What’s Next

I am hoping this is all the information you need to get started with FirePHP Companion. It’s a feature-packed tool that will only get better and I hope you will follow it’s progress. I will be posting a lot more information, tutorials and screencasts so subscribe to my blog or follow me on twitter.

My last post Integrating FirePHP for Ajax Development kind of paints a picture for what I have been up to:

I have never been a real fan of interactive debuggers, primarily because they don’t support my write a little code, run it, write some more, re-run it  development approach, which seems to be quite common when building Web applications with scripting languages. As FirePHP is coming into its own and I can observe how others use it, I see tremendous opportunity in evolving this type of development approach further. I’m not talking here about just the debugging aspect, but rather a system that can easily be tied into any application to provide the developer with a powerful user interface that can visualize the internals of an application. One that allows the developer to configure components for different environments and stages of the development cycle.

To that end I have been working on a new development and debugging system for PHP and JavaScript applications that takes these kinds of features (and much more) to heart. What I am really excited about is that I have been able to build the whole thing primarily in JavaScript and architect it in such a way that it may be incrementally integrated into existing applications and workflows.

It has been a difficult decision to make as to when to shift focus away from the primary research and development and start supporting users on the system but I think it’s time to publish what I have accomplished so far. I am going to be releasing a bunch of Developer Companion tools in phases with the initial focus on taking FirePHP to the next level.

This developer tools project has been a long dream of mine and I hope to make a real difference in how we write modern web applications by bringing the level of functionality we are used to from Web 2.0 applications these days to the toolchain.

I realize what I have mentioned so far is vague but you have to start somewhere in condensing many years of work into a brief heads-up. Next steps are to redo my website, I already have a design from 99designs, and get FirePHP Companion better introduced (forgive my amateur unfocused freecasting skills … they can only get better!).

Lastly, I hate to burst your bubble if you are expecting regular posts and production ready tools right away. You can start to follow and get involved with what will slowly trickle out but I still need some more time to get a consistent workflow going that I can maintain including tweets, posts and screencasts.

I hope you will follow me on this journey and most importantly that you will benefit from my efforts as that is my whole reason for doing this. Solving real problems we face every day.

Since writing this article I have been working on FirePHP 1.0 and a new client tool to achieve the kinds of things I describe below much more easily. The new tool is called FirePHP Companion and aimed at streamlining the PHP development workflow. There is still a lot of work left to do, but you can already take a look at how the demo provided here can be implemented easily with FirePHP Companion.

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.

This is not a step-by-step tutorial. I have made a complete demo available for download, along with some useful libraries illustrating all the concepts covered here. I want to emphasize that the demo is only one possible implementation. There are many other possibilities.

The Problem

Building AJAX applications brings some new challenges to PHP developers. Apart from the fact that you need to learn JavaScript, which is probably a good idea anyway, you need to figure out a way to debug your AJAX requests. There are primarily two ways to do that.

The more involved option is to use an IDE with an integrated debugger. While this may be the most powerful approach, it typically is also the most complex, expensive, time-consuming and cumbersome, especially when it comes to triggering the debugger for a specific request.

The second option is to simply print out debug information using var_dump() or print_r(). This approach requires you to examine the response of the request in Firebug, or to run it in its own browser tab. It also breaks your JavaScript AJAX code, because the response is no longer a valid XML or JSON structure.

The ideal solution would be something that is easy to set up and use; something that will allow you to view any PHP variable without breaking the response content, so that your JavaScript code can continue to execute as intended. This is precisely what FirePHP is designed to do — this, and more.

The FirePHP Solution

FirePHP solves the problem of AJAX debugging by sending debug information along with the response. To avoid breaking the response content, the debug information is placed into special HTTP response headers. This works for all types of requests, not just AJAX requests, which means you can even debug requests for images that are dynamically generated by a PHP script. You can use FirePHP in your development environment, or use it to track down bugs that only appear on your production site.

The FirePHP system requires two components to work. The first of these comes in the form of a Firefox Extension that extends Firebug. It reads the special response headers and presents the debug data in an intelligent way within Firebug. The second component is a PHP server library that provides the necessary functionality to encode PHP variables and sends them in the response headers.

Detailed information regarding how to install the FirePHP components and how to get started with their basic functionality is available on the FirePHP website, to which you will be directed when you install the FirePHP Firefox extension.

Persistent and Controllable

There is significant benefit in leaving debugging code in your application and being able to easily enable the desired debug output as and when required. This is primarily useful when working with object oriented code, where common components are re-used in different areas of the application and may become part of several iterations of debugging when tied into different end-user functionality. One such component, for example, would be a caching object.

When debugging such an object, you would typically want to be able to view information about the cache such as filenames, whether the data was created or fetched from the cache, and when the cache entry will expire. Going one step further, during debugging, you would want to be able to control the cache lifetime, force cache expiry, and conduct some analysis on the amount of resources used and time taken to create the data that is being cached.

Having debugging code in your application and being able to trigger it in a secure way may also come in extremely handy when something that worked fine during development is not working quite as it should in your production environment. In such a case, you’ll want to be able to easily view specific information about your backend without making it available to all.

Design Philosophy

FirePHP is designed to be non-intrusive so that you can decide how and where to use it within your application. It essentially provides a mechanism to send logging events to the Firebug Console without interfering with your application. There is no built-in security to safeguard the data you send, which means that you are in charge of security and in charge of deciding what to send, when to send it and to whom.

All data is sent in clear text in the response headers, unless the request was made via HTTPS in which case the entire response —including the headers— will be encrypted.

Although the chosen design may put the burden of security on you, it gives you complete freedom over how to use FirePHP within your application. The remainder of this discussion will focus on the best practices of how to integrate FirePHP into your application to implement some powerful debugging functionality while ensuring security and maintaining flexibility. A basic understanding of the FirePHP API will help, but is not essential.

Enabling FirePHP

As soon as you include the FirePHP server library in your application, FirePHP is enabled and you can log to Firebug:

FB::log('This is a log message');

This makes it very easy to get started, and provides a great alternative to using var_dump() or print_r() during development or ad-hock debugging. When you use FirePHP in this way, you would typically only log variables during development and remove all your logging statements before uploading your code to a production server.

If there are logging statements you want to keep in your code, to save you time in future, you can manually disable FirePHP with

FB::setEnabled(false);

before uploading your code. This will stop your logging messages from being sent. However, if you rely on this method, apart from the fact that it is cumbersome, there will likely come a time when you forget to disable it before uploading your code. In that case anyone who has FirePHP installed will be able to see your logging messages, which may or may not be a problem depending on the data you are logging. You probably don’t want that to happen.

A better approach would be to use a configuration setting to determine whether FirePHP should be enabled. Chances are your application already uses a configuration file you can use. Adhering to good security principles, you will want to disable FirePHP by default and only enable it if a setting is found that specifically overrides the default. The code could look something like this:

$settings = @parse_ini_file('settings.ini');
 
if ($settings['FirePHP'] == 'Enabled') {
  FB::setEnabled(true);
} else {
  FB::setEnabled(false);
}

When this is set up, all you will need to do is use different values in your configuration files in your development and production environments, and you will never need to worry about FirePHP being enabled by accident again.

If you want to enable FirePHP for specific users no matter which environment the application is running in, you can tie the above code into your user privilege or session system.

Selective Logging

To realize selective logging by allowing a user —or more specifically, a developer— to turn on and off specific groups of logging messages, requires a bit more work. Such a system typically consists of an administration interface allowing the developer to tweak logging options, and a wrapper object for FirePHP that is used in the application to intercept logging messages and only send them if requested.

The options defined in the administration interface will need to be accessible to the wrapper in the application. This can be done on the back-end via a shared session or cached file, or on the front-end via cookies. The approach you choose depends on how your application is structured and whether the administration system runs on the same domain as your application. The cookie approach is probably the easiest to set up, allowing the administration interface to be coded entirely in JavaScript.

Let’s say you implement the administration interface for the debugging options in JavaScript. The user interface could be tailored to look consistent with the rest of your administration system, and could be used to set, say, a cookie named Debug to a value of DisableCache when that option is selected.

Your wrapper on the application side would look something like this:

class Debug
{
  public static function getOption($name)
  {
    $options = @explode('|', $_COOKIE['Debug']);
    return(is_array($options) &&
    in_array($name, $options)) ? true : false;
  }
}

You can then ask the wrapper whether a specific option is enabled, and act accordingly:

if (Debug::getOption('DisableCache')) {
  // code to disable cache
  FB::info('Cache has been disabled!');
} else {
  // default code
}

Make sure that the debugging options always override default behaviour, and that the application will continue to function if no debug cookie or option is defined. You should always return FALSE for the debug options if the user is not authorized to use them.

I encourage you to look at the source code of the demo mentioned earlier, which illustrates the cookie and JavaScript-based administration interface approach. Rip out the code you like and make it your own.

An Eye to the Future

I have been toying around with development and debugging systems for a long time. FirePHP is my first public, stable and practical implementation to a problem area I find fascinating.

I have never been a real fan of interactive debuggers, primarily because they don’t support my write a little code, run it, write some more, re-run it development approach, which seems to be quite common when building Web applications with scripting languages. As FirePHP is coming into its own and I can observe how others use it, I see tremendous opportunity in evolving this type of development approach further. I’m not talking here about just the debugging aspect, but rather a system that can easily be tied into any application to provide the developer with a powerful user interface that can visualize the internals of an application. One that allows the developer to configure components for different environments and stages of the development cycle.

It would be much easier for a new developer to learn their way around a codebase if they could see the order of execution visually on one page without having to step through the code. It would be trivial to provide mock data to application objects where certain services or classes are not yet complete by defining the data in your browser.

I encourage you to look both at FirePHP and at the big picture it points to. FirePHP represents a humble beginning to a problem area that is desperate for attention, and provides an enormous opportunity to make all our lives easier.

UPDATE: Oct 20, 2010

Since writing this article I have been working on FirePHP 1.0 and a new client tool to achieve what I described above. There is still a lot of work left to do, but you can already take a look at how the demo provided here can be implemented much more easily with FirePHP Companion.