designcise / bitframe-whoops
Whoops error handler middleware
Requires
- php: >=8.1
- filp/whoops: ~2.14
- psr/http-factory: ~1.0
- psr/http-server-handler: ~1.0
- psr/http-server-middleware: ~1.0
Requires (Dev)
- mockery/mockery: ^1.4
- phpmd/phpmd: @stable
- phpstan/phpstan: *
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: 3.*
README
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.1.0 or newer.
Quickstart
Instantiating
The constructor has the following signature:
new ErrorHandler( \Psr\Http\Message\ResponseFactoryInterface, \BitFrame\Whoops\Provider\HandlerProviderNegotiator::class [options] );
- The first argument to the constructor must be an instance of
Psr\Http\Message\ResponseFactoryInterface
; - The second argument to the constructor must be an implementation of
\BitFrame\Whoops\Provider\ProviderInterface
; - The third argument to the constructor is an optional array of options to specify the following:
catchGlobalErrors
: When set totrue
errors will be handled outside of current batch of middleware set.- Other options are simply method names in
Whoops\Handler\*Handler.php
andBitFrame\Whoops\Handler\*Handler.php
. For example, to setWhoops\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 provders are included:
BitFrame\Whoops\Provider\HtmlHandlerProvider
forWhoops\Handler\PrettyPageHandler
;BitFrame\Whoops\Provider\JsonHandlerProvider
forWhoops\Handler\JsonResponseHandler
;BitFrame\Whoops\Provider\JsonpHandlerProvider
forBitFrame\Whoops\Handler\JsonpResponseHandler
;BitFrame\Whoops\Provider\TextHandlerProvider
forWhoops\Handler\PlainTextHandler
;BitFrame\Whoops\Provider\XmlHandlerProvider
forWhoops\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.