Add support for an optional onError callback

.gitattributes

@@ -5,6 +5,6 @@
 .gitattributes       export-ignore
 .gitignore           export-ignore
 .php-cs-fixer.php    export-ignore
-phpcs.xml.dist       export-ignore
-phpunit.xml.dist     export-ignore
+phpcs.xml            export-ignore
+phpunit.xml          export-ignore
 .phpstan.neon        export-ignore

CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.2.0] - 2025-04-22
+### Added
+- Support for [PSR-3 Logger](https://github.com/php-fig/log). Example using [Monolog](https://github.com/Seldaek/monolog):
+
+With default logging:
+```php
+use Monolog\Level;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+$logger = new Logger('app');
+$logger->pushHandler(new StreamHandler('path/to/your.log', Level::Warning));
+
+$response = Dispatcher::run([
+    new ErrorHandler(null, $logger),
+    function ($request) {
+        throw new Exception('Something went wrong');
+    },
+]);
+
+```
+With a custom log callback:
+```php
+use Monolog\Level;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+$logger = new Logger('app');
+$logger->pushHandler(new StreamHandler('path/to/your.log', Level::Warning));
+
+$response = Dispatcher::run([
+    (new ErrorHandler(null, $logger))
+        ->logCallback(function (
+            LoggerInterface $logger,
+            Throwable $error,
+            ServerRequestInterface $request
+        ): void {
+            $logger->critical('Uncaught exception', [
+                'message' => $error->getMessage(),
+                'request' => [
+                    'uri' => $request->getUri()->getPath(),
+                ]
+            ]);
+        }),
+    function ($request) {
+        throw new Exception('Something went wrong');
+    },
+]);
+```
+
 ## [3.1.0] - 2025-03-21
 ### Fixed
 - Support for PHP typing.
@@ -117,6 +167,7 @@ First version
 
 [#9]: https://github.com/middlewares/error-handler/issues/9
 
+[3.2.0]: https://github.com/middlewares/error-handler/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/middlewares/error-handler/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/middlewares/error-handler/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/middlewares/error-handler/compare/v3.0.0...v3.0.1

README.md

@@ -27,6 +27,9 @@ composer require middlewares/error-handler
 use Middlewares\ErrorFormatter;
 use Middlewares\ErrorHandler;
 use Middlewares\Utils\Dispatcher;
+use Monolog\Level;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
 
 // Create a new ErrorHandler instance
 // Any number of formatters can be added. One will be picked based on the Accept
@@ -41,14 +44,18 @@ $errorHandler = new ErrorHandler([
     new ErrorFormatter\XmlFormatter(),
 ]);
 
+// Create logger (optional)
+$logger = new Logger('app');
+$logger->pushHandler(new StreamHandler('path/to/your.log', Level::Warning));
+
 // ErrorHandler should always be the first middleware in the stack!
 $dispatcher = new Dispatcher([
     $errorHandler,
     // ...
     function ($request) {
         throw HttpErrorException::create(404);
     }
-]);
+], $logger);
 
 $request = $serverRequestFactory->createServerRequest('GET', '/');
 $response = $dispatcher->dispatch($request);
@@ -67,6 +74,40 @@ $errorHandler = new ErrorHandler([
 
 **Note:** If no formatter is found, the first value of the array will be used. In the example above, `HtmlFormatter`.
 
+### How to setup a custom log callback
+
+This allows you to fully customize how you log (level, message, context, etc.) with access to values such as `Throwable` and `ServerRequestInterface` instances.
+
+Example using Monolog:
+
+```php
+use Monolog\Level;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+$logger = new Logger('app');
+$logger->pushHandler(new StreamHandler('path/to/your.log', Level::Warning));
+
+$response = Dispatcher::run([
+    (new ErrorHandler(null, $logger))
+        ->logCallback(function (
+            LoggerInterface $logger,
+            Throwable $error,
+            ServerRequestInterface $request
+        ): void {
+            $logger->critical('Uncaught exception', [
+                'message' => $error->getMessage(),
+                'request' => [
+                    'uri' => $request->getUri()->getPath(),
+                ]
+            ]);
+        }),
+    function ($request) {
+        throw new Exception('Something went wrong');
+    },
+]);
+```
+
 ### How to use a custom response for Production
 
 ```php

composer.json

@@ -20,17 +20,19 @@
     },
     "require": {
         "php": "^7.2 || ^8.0",
+        "ext-gd": "*",
         "middlewares/utils": "^2 || ^3 || ^4",
         "psr/http-server-middleware": "^1",
-        "ext-gd": "*"
+        "psr/log": "^1 || ^2 || ^3"
     },
     "require-dev": {
         "phpunit/phpunit": "^8 || ^9",
         "friendsofphp/php-cs-fixer": "^3",
         "squizlabs/php_codesniffer": "^3",
         "oscarotero/php-cs-fixer-config": "^2",
         "phpstan/phpstan": "^1 || ^2",
-        "laminas/laminas-diactoros": "^2 || ^3"
+        "laminas/laminas-diactoros": "^2 || ^3",
+        "filisko/fake-psr3-logger": "^1.0"
     },
     "autoload": {
         "psr-4": {
@@ -50,4 +52,4 @@
         "coverage": "phpunit --coverage-text",
         "coverage-html": "phpunit --coverage-html=coverage"
     }
-}
+}

src/ErrorHandler.php

@@ -14,20 +14,29 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
+use Psr\Log\LoggerInterface;
 use Throwable;
 
 class ErrorHandler implements MiddlewareInterface
 {
     /** @var FormatterInterface[] */
     private $formatters = [];
 
+    /** @var LoggerInterface|null */
+    private $logger = null;
+
+    /** @var callable|null */
+    private $logCallback = null;
+
     /**
      * Configure the error formatters
      *
      * @param FormatterInterface[] $formatters
      */
-    public function __construct(?array $formatters = null)
+    public function __construct(?array $formatters = null, ?LoggerInterface $logger = null)
     {
+        $this->logger = $logger;
+
         if (empty($formatters)) {
             $formatters = [
                 new PlainFormatter(),
@@ -54,11 +63,33 @@ public function addFormatters(FormatterInterface ...$formatters): self
         return $this;
     }
 
+    /**
+     * Set a custom log callback
+     */
+    public function logCallback(callable $callback): self
+    {
+        $this->logCallback = $callback;
+
+        return $this;
+    }
+
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
         try {
             return $handler->handle($request);
         } catch (Throwable $error) {
+            if ($this->logger) {
+                if ($this->logCallback) {
+                    ($this->logCallback)($this->logger, $error, $request);
+                } else {
+                    $this->logger->critical('Uncaught exception', [
+                        'message' => $error->getMessage(),
+                        'file' => $error->getFile(),
+                        'line' => $error->getLine(),
+                    ]);
+                }
+            }
+
             foreach ($this->formatters as $formatter) {
                 if ($formatter->isValid($error, $request)) {
                     return $formatter->handle($error, $request);

tests/ErrorHandlerTest.php

@@ -4,6 +4,7 @@
 namespace Middlewares\Tests;
 
 use Exception;
+use Filisko\FakeLogger;
 use Middlewares\ErrorFormatter\HtmlFormatter;
 use Middlewares\ErrorFormatter\ImageFormatter;
 use Middlewares\ErrorFormatter\JsonFormatter;
@@ -15,6 +16,9 @@
 use Middlewares\Utils\Factory;
 use Middlewares\Utils\HttpErrorException;
 use PHPUnit\Framework\TestCase;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Log\LoggerInterface;
+use Throwable;
 
 class ErrorHandlerTest extends TestCase
 {
@@ -61,6 +65,65 @@ public function getStatusCode(): int
         $this->assertEquals(418, $response->getStatusCode());
     }
 
+    public function testLoggerException(): void
+    {
+        $logger = new FakeLogger();
+
+        $response = Dispatcher::run([
+            new ErrorHandler(null, $logger),
+            function ($request) {
+                throw new Exception('Something went wrong');
+            },
+        ]);
+
+        $this->assertEquals(500, $response->getStatusCode());
+        $this->assertEquals([[
+            'level' => 'critical',
+            'message' => 'Uncaught exception',
+            'context' => [
+                'message' => 'Something went wrong',
+                'file' => __FILE__,
+                'line' => 75,
+            ]
+        ]], $logger->logs());
+    }
+
+    public function testLoggerExceptionWithCustomCallback(): void
+    {
+        $logger = new FakeLogger();
+
+        $response = Dispatcher::run([
+            (new ErrorHandler(null, $logger))
+                ->logCallback(function (
+                    LoggerInterface $logger,
+                    Throwable $error,
+                    ServerRequestInterface $request
+                ): void {
+                    $logger->critical('Uncaught exception', [
+                        'message' => $error->getMessage(),
+                        'request' => [
+                            'uri' => $request->getUri()->getPath(),
+                        ]
+                    ]);
+                }),
+            function ($request) {
+                throw new Exception('Something went wrong');
+            },
+        ]);
+
+        $this->assertEquals(500, $response->getStatusCode());
+        $this->assertEquals([[
+            'level' => 'critical',
+            'message' => 'Uncaught exception',
+            'context' => [
+                'message' => 'Something went wrong',
+                'request' => [
+                    'uri' => '/',
+                ]
+            ]
+        ]], $logger->logs());
+    }
+
     public function testGifFormatter(): void
     {
         $request = Factory::createServerRequest('GET', '/');