Whoops PHP Error Handling Framework

Whoops is a stack-based error handling framework. You create an instance of Whoops\Run and push one or more handlers onto the stack using pushHandler(). When an error occurs, Whoops iterates through the handlers until one successfully processes the exception.

Capturing HTML output manually

If you want to collect the generated HTML instead of letting Whoops output it directly to the browser, you can disable quitting and direct output:

$whoops = new \Whoops\Run;
$whoops->allowQuit(false);
$whoops->writeToOutput(false);
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$html = $whoops->handleException($e);

To use a Whoops integration for a specific framework, add the integration package to your project's composer.json file. This will install both the integration and the core Whoops library.

"require": {
    "username/whoops-someframework": "*"
}

You can replay errors that occurred in a production environment by serializing the exception and storing it. To replay the error in a local development environment using Whoops, unserialize the exception and pass it to the handleException() method of a Whoops\Run instance configured with a handler (such as PrettyPageHandler).

$serialized_exception = serialize(new Exception('Something has happened!'));

// Later, in your development environment:
$whoops = new \Whoops\Run;
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler);
$whoops->register();
$whoops->handleException(unserialize($serialized_exception));

Whoops prefers that framework-specific integrations are maintained in separate repositories rather than within the Whoops core. To create an official integration:

1. Maintain your integration classes and documentation in your own repository.
2. Create a composer.json file in your repository that requires filp/whoops.
3. Register your package with Packagist.
4. Once published, create an issue in the Whoops repository so a link to your integration can be added to the Whoops README.

Framework users can then install your integration via Composer, which will automatically pull in the required filp/whoops dependency.

{
    "name": "username/whoops-someframework",
    "description": "Integrates the Whoops library into SomeFramework",
    "require": {
        "filp/whoops": "1.*
    }
}

When using the PrettyPageHandler, you can configure Whoops to open the files referenced in an error directly in your IDE or editor. This feature requires that your PHP source files are locally accessible on the machine where the editor is installed.

To enable this, use the setEditor() method on your PrettyPageHandler instance and pass the identifier for your preferred editor.

<?php

use Whoops//
use Whoops\Handler\PrettyPageHandler;

$handler = new PrettyPageHandler;
$handler->setEditor('sublime');

To use Whoops in a standalone PHP project, install it via Composer and register the PrettyPageHandler to enable a visual error interface.

1. Install the package:

   composer require filp/whoops

2. Register the handler in your application entry point:

   $whoops = new //Whoops/Run;
   $whoops->pushHandler(new //Whoops/Handler/PrettyPageHandler);
   $whoops->register();

The CallbackHandler allows you to use a standard PHP closure as a Whoops handler. This is useful for simple logic or quick debugging without creating a full class.

When you pass a closure to Whoops\Run::appendHandler() or prependHandler(), Whoops automatically wraps it in a CallbackHandler.

use Whoops\Handler\Handler;

$run->appendHandler(function($exception, $inspector, $run) {
    var_dump($exception->getMessage());
    return Handler::DONE;
});

The Inspector class provides a high-level interface for examining an exception and its stack trace. It is useful for handlers that need to extract specific details about the error.

Available methods:

• getException(): Returns the original Exception object.
• getExceptionName(): Returns the class name of the exception.
• getExceptionMessage(): Returns the exception message.
• getFrames(): Returns an iterator for all frames in the stack trace.