Zend Server + FirePHP on AWS
January 6, 2011

FirePHP can nicely complement the built-in tools available when using Zend Server and can be easily made available to all provisioned sites. This tutorial illustrates how to setup FirePHP 1.0 for all virtual hosts on a Zend Server AMI on Amazon EC2.

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

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.

Leave a Comment




Linkbacks