gadwinn / error-catcher-middleware
PSR-15 middleware turning exceptions and PHP errors into a response, with an optional fatal error handler.
Package info
github.com/Gadwinn/error-catcher-middleware
pkg:composer/gadwinn/error-catcher-middleware
Requires
- php: >=8.3
- psr/http-message: ^1.1 || ^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
Requires (Dev)
- phpdocumentor/shim: *
- phpstan/phpstan: *
- phpunit/phpunit: *
- povils/phpmnd: *
- roave/security-advisories: dev-latest@dev
- squizlabs/php_codesniffer: *
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 11:17:27 UTC
README
A PSR-15 middleware that turns unhandled exceptions and PHP errors into an HTTP response, with an optional safety net for fatal errors.
- No dependency besides the PSR interfaces (PSR-7, PSR-15).
- No global or static state: safe with long-running workers (FrankenPHP worker mode, RoadRunner…).
Requirements
- PHP >= 8.3
Installation
composer require gadwinn/error-catcher-middleware
Usage
The middleware takes one closure, which receives the Throwable and returns the response to send:
use G\ErrorCatcherMiddleware\ErrorCatcherMiddleware; use Psr\Http\Message\ResponseInterface; $middleware = new ErrorCatcherMiddleware( function (Throwable $e) use ($responseFactory, $logger): ResponseInterface { $logger->error($e->getMessage(), ['exception' => $e]); $response = $responseFactory->createResponse(500); $response->getBody()->write('Internal Server Error'); return $response; }, );
Place it outermost in the pipeline, so that it wraps every other middleware and the application handler.
What is caught
| Scenario | Behaviour |
|---|---|
Exception or Error thrown while handling the request |
Passed to the closure |
| PHP warning / notice | Converted to an ErrorException, passed to the closure |
Error excluded by error_reporting() or silenced with @ |
Ignored (PHP's standard handling) |
Deprecation (E_DEPRECATED, E_USER_DEPRECATED) |
Never converted: logged or displayed by PHP according to its settings |
Fatal error (E_ERROR, E_PARSE, …) |
Not catchable by a middleware, see below |
The PHP error handler is installed for the duration of process() only, and the previous one is restored afterwards.
Fatal errors
A fatal error (out of memory, timeout, parse error…) stops the script: no response object can be returned any more. Register a shutdown handler once, when the application boots:
// Default: status 500 and "Internal Server Error" as plain text ErrorCatcherMiddleware::registerShutdownHandler(); // Or your own output ErrorCatcherMiddleware::registerShutdownHandler(static function (ErrorException $e): void { if (!headers_sent()) { http_response_code(500); header('Content-Type: application/json'); } echo json_encode(['error' => 'Internal Server Error']); });
The handler must output directly. Nothing is registered unless you call this method, and each call registers one more handler: in worker mode, call it before the request loop, not inside it.
Development
composer install composer test-all
License
MIT