Pretty error display for PHP

One of my pet peeves regarding PHP is the terseness of the error messages it throws. Not that they are unhelpful; the major headache it that one has to open the source file at the given error location to check for problems. Also the complete system context (the PHP system variables, cookies, session etc.) is not easily available.

Whoops is a nice little library that helps you develop and maintain your PHP projects better, by helping you deal with errors and exceptions in a user friendly way. Whoops is already a part of Laravel 4, and includes providers for Silex and Zend Framework 2.

Take the following simple code.

$planets = array();
echo $planets[0];

Executing this throws the following PHP error.

Notice: Undefined offset: 0 in D:\localhost\projects\test\test.php on line 27

The same error with Whoops enabled is shown below (click for a larger view). The actual error page contains even more information than given here – session variables, cookies, HTTP headers etc.

whoops-error

Installing Whoops

Whoops can be easily installed by using Composer by adding the following lines to the composer.json file. If you are unfamiliar with Composer you can do a manual install instead by downloading the Zip file.

{
    "require": {
        "filp/whoops": "1.*"
    }
}

Whoops uses PHP namespaces and includes many classes so it is better to use your frameworks auto-loading feature to load the Whoop libraries from your project files. Still, if you need to add Whoops to any applications that does not have auto-loading you can directly reference the relevant Whoops classes as shown in the following example.

<?php
 
/* Make sure that the Whoops directory is set in your PHP includes path */
require_once('Whoops/Run.php');
require_once('Whoops/Handler/HandlerInterface.php');
require_once('Whoops/Handler/Handler.php');
require_once('Whoops/Handler/PrettyPageHandler.php');
require_once('Whoops/Handler/JsonResponseHandler.php');
require_once('Whoops/Exception/ErrorException.php');
require_once('Whoops/Exception/Inspector.php');
require_once('Whoops/Exception/Frame.php');
require_once('Whoops/Exception/FrameCollection.php');
 
$run     = new \Whoops\Run;
$handler = new \Whoops\Handler\PrettyPageHandler;
$JsonHandler = new \Whoops\Handler\JsonResponseHandler;
 
$run->pushHandler($JsonHandler);
$run->pushHandler($handler);
$run->register();
 
/* Sample code that throws an error */
 
$planets = array();
echo $planets[0];
 
?>

You can even add some additional information to the error page with the following

$run     = new \Whoops\Run;
$handler = new \Whoops\Handler\PrettyPageHandler;
$JsonHandler = new \Whoops\Handler\JsonResponseHandler;
 
/* Set the page's title */
$handler->setPageTitle("Oops, Error encountered!");
 
/* Some additional contextual information if required */
$handler->addDataTable("Extra Slice of Info", array(
      "page-id"     => 173,
      "page-name"   => "foo-bar",
      "app-name"    => "fb"
));
 
$run->pushHandler($handler);
$run->register();

There are many more options to Whoops, the details regarding which can be found here. The ones given above however will be enough for most projects.