BitFrame\Whoops

Whoops error handler middleware to handle application or middleware specific errors.

Installation

$ composer require "designcise/bitframe-whoops"

Please note that this package requires PHP 8.2.0 or newer.

Quickstart

Instantiating

The constructor has the following signature:

new ErrorHandler(
    ResponseFactoryInterface,
    HandlerProviderNegotiator::class,
    [options],
);

1. The first argument to the constructor must be an instance of Psr\Http\Message\ResponseFactoryInterface;
2. The second argument to the constructor must be an implementation of \BitFrame\Whoops\Provider\ProviderInterface;
3. The third argument to the constructor is an optional array of options to specify the following:
   1. catchGlobalErrors: When set to true errors will be handled outside of current batch of middleware set.
   2. Other options are simply method names in Whoops\Handler\*Handler.php and BitFrame\Whoops\Handler\*Handler.php. For example, to set Whoops\Handler\JsonResponseHandler::setJsonApi() you would pass in: ['setJsonApi' => false], etc.

As a shortcut, you can also use the static method ErrorHandler::fromNegotiator($factory, $options). This would use the \BitFrame\Whoops\Provider\HandlerProviderNegotiator by default.

How to Run the Middleware

To run the middleware, simply pass in a BitFrame\Whoops\ErrorHandler instance to your middleware runner / dispatcher.

For example, to handle middleware-specific errors with BitFrame\App (or other PSR-15 dispatchers) it would look something like this:

use BitFrame\App;
use BitFrame\Emitter\SapiEmitter;
use BitFrame\Whoops\ErrorHandler;
use BitFrame\Whoops\Provider\HandlerProviderNegotiator;
use BitFrame\Factory\HttpFactory;

$app = new App();

$middleware = function () {
    throw new \Exception('hello world!');
};

$app->use([
    SapiEmitter::class,
    new ErrorHandler(HttpFactory::getFactory(), HandlerProviderNegotiator::class, [
        'addTraceToOutput' => true,
        'setJsonApi' => false,
    ]),
    $middleware,
]);

$app->run();

To handle global errors with BitFrame\App (or other PSR-15 dispatchers) it would look something like this:

use BitFrame\App;
use BitFrame\Whoops\ErrorHandler;
use BitFrame\Factory\HttpFactory;

$app = new App();

$app->run([
    ErrorHandler::fromNegotiator(HttpFactory::getFactory(), [
        'catchGlobalErrors' => true,
        'addTraceToOutput' => true,
        'setJsonApi' => false,
    ]),
]);

throw new \Exception('hello world!');

How Does It Work?

The error handler middleware automatically determines the error handler to use based on the Accept header. The following error handler providers are included:

1. BitFrame\Whoops\Provider\HtmlHandlerProvider for Whoops\Handler\PrettyPageHandler;
2. BitFrame\Whoops\Provider\JsonHandlerProvider for Whoops\Handler\JsonResponseHandler;
3. BitFrame\Whoops\Provider\JsonpHandlerProvider for BitFrame\Whoops\Handler\JsonpResponseHandler;
4. BitFrame\Whoops\Provider\TextHandlerProvider for Whoops\Handler\PlainTextHandler;
5. BitFrame\Whoops\Provider\XmlHandlerProvider for Whoops\Handler\XmlResponseHandler;

Tests

To run the tests you can use the following commands:

Command	Type
composer test	PHPUnit tests
composer style	CodeSniffer
composer md	MessDetector
composer check	PHPStan

Contributing

• File issues at https://github.com/designcise/bitframe-whoops/issues
• Issue patches to https://github.com/designcise/bitframe-whoops/pulls

Documentation

Complete documentation for v3 will be available soon.

License

Please see License File for licensing information.