php errors for cool kids
Switch branches/tags
Nothing to show
Pull request Compare This branch is 767 commits behind filp:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


php errors for cool kids

Build Status


whoops is an error handler base/framework for PHP. Out-of-the-box, it provides a pretty error interface that helps you debug your web projects, but at heart it's a simple yet powerful stacked error handling system.

This library is currently in a heavy development phase, and may catch on fire at any moment.

(current) Features

  • Flexible, stack-based error handling
  • Stand-alone library with (currently) no required dependencies
  • Simple API for dealing with exceptions, trace frames & their data
  • Includes a pretty rad error page for your webapp projects
  • Includes a Silex\WhoopsServiceProvider for painless integration with Silex
  • Includes an Illuminate\WhoopsServiceProvider for equally painless integration with Laravel 4
  • Easy to extend and integrate with existing libraries
  • Clean, well-structured & tested code-base (well, except pretty-template.php, for now...)


  • Install Composer and place the executable somewhere in your $PATH (for the rest of this README, I'll reference it as just composer)

  • Add filp/whoops to your project's `composer.json:

    "require": {
        "filp/whoops": "dev-master"
  • Install/update your dependencies
$ cd my_project
$ composer install

And you're good to go! Have a look at the example files in examples/ to get a feel for how things work. I promise it's really simple!

Integrating with Silex

whoops comes packaged with a Silex Service Provider: Whoops\Provider\Silex\WhoopsServiceProvider. Using it in your existing Silex project is easy:

require 'vendor/autoload.php';

use Silex\Application;

// ... some awesome code here ...

if($app['debug']) {
    $app->register(new Whoops\Provider\Silex\WhoopsServiceProvider);

// ...


And that's about it. By default, you'll get the pretty error pages if something goes awry in your development environment, but you also have full access to the whoops library, obviously. For example, adding a new handler into your app is as simple as extending whoops:

$app['whoops'] = $app->extend('whoops', function($whoops) {
    $whoops->pushHandler(new DeleteWholeProjectHandler);
    return $whoops;

Integrating with Laravel 3

User @hdias contributed a simple guide/example to help you integrate whoops with Laravel 3's IoC container, available at:

(note: This example still references whoops by its old name (damnit), be sure to update it accordingly)

Integrating with Laravel 4/Illuminate

User @schickling contributed a service provider for Laravel 4. Just include this in your app/config/app.php in the "providers" array:


Alternatively, @dberry37388's laravel4-support package also integrates whoops into your fancy-schmancy Laravel stack.

Available Handlers

whoops currently ships with the following built-in handlers, available in the Whoops\Handler namespace:

  • PrettyPageHandler - Shows a pretty error page when something goes pants-up
  • CallbackHandler - Wraps a closure or other callable as a handler. You do not need to use this handler explicitly, whoops will automatically wrap any closure or callable you pass to Whoops\Run::pushHandler
  • JsonResponseHandler - Captures exceptions and returns information on them as a JSON string. Can be used to, for example, play nice with AJAX requests.


If you want to help, great! Here's a couple of steps/guidelines:

  • Fork/clone this repo, and update dev dependencies using Composer
$ git clone
$ cd whoops
$ composer install --dev
  • Create a new branch for your feature or fix
$ git checkout -b feature/flames-on-the-side
  • Add your changes & tests for those changes (in tests/).
  • Remember to stick to the existing code style as best as possible. When in doubt, follow PSR-2.
  • Send me a pull request!

If you don't want to go through all this, but still found something wrong or missing, please open a new issue report so that I or others may take care of it.

TODO/tasks (very short & rough list of current goals)

  • Improve code view
  • Delay prettify until needed, instead of doing it for every frame at once
  • Cleanup API, specially around Frame handling
  • Add extension hooks for PrettyPageHandler
  • Improve test coverage