Whoops error handler middleware

v4.0.0 2023-07-01 23:51 UTC

This package is auto-updated.

Last update: 2024-05-30 00:48:09 UTC


CI Maintainability Test Coverage

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


$ composer require "designcise/bitframe-whoops"

Please note that this package requires PHP 8.2.0 or newer.



The constructor has the following signature:

new ErrorHandler(
  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!');

    new ErrorHandler(HttpFactory::getFactory(), HandlerProviderNegotiator::class, [
        'addTraceToOutput' => true,
        'setJsonApi' => false,


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();

    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;


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



Complete documentation for v3 will be available soon.


Please see License File for licensing information.