feat: Add a config for exception management (#20)

Closes #18

README.md

@@ -130,3 +130,36 @@ class MyMiddleware implements Middleware
 
 You can do whatever you want in your middleware. If something went wrong, the procedure is the same as for
 RequestHandler.
+
+### Special response handling
+
+By special, we mean 404, 500, ... In short HTTP code different from 2XX. By default, Archict will use `ResponseHandler`
+which just set the corresponding headers. Via the config file of this Brick you change this behavior:
+
+```yaml
+error_handling:
+  404: \MyHandler
+  501: 'Oops! Something went wrong'
+```
+
+You have 2 choices:
+
+1. Pass a string, Archict will use it as response body
+2. Pass a class string of a class implementing interface `ResponseHandler`, Archict will call it. For example:
+
+```php
+<?php
+
+use Archict\Router\ResponseHandler;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class MyHandler implements ResponseHandler
+{
+    public function handleResponse(ResponseInterface $response, ServerRequestInterface $request): ResponseInterface
+    {
+        $factory = new \GuzzleHttp\Psr7\HttpFactory();
+        return $response->withBody($factory->createStream("Page '{$request->getUri()->getPath()}' not found!"));
+    }
+}
+```

include/Config/ConfigurationValidator.php

@@ -0,0 +1,59 @@
+<?php
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024-Present Kevin Traini
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Archict\Router\Config;
+
+use Archict\Router\Exception\ErrorHandlerShouldImplementInterfaceException;
+use Archict\Router\Exception\HTTPCodeNotHandledException;
+use Archict\Router\ResponseHandler;
+use ReflectionClass;
+
+/**
+ * @internal
+ */
+final class ConfigurationValidator
+{
+    /**
+     * @throws HTTPCodeNotHandledException
+     * @throws ErrorHandlerShouldImplementInterfaceException
+     */
+    public function validate(RouterConfiguration $configuration): void
+    {
+        foreach ($configuration->error_handling as $code => $handler) {
+            if ($code < 400 || $code >= 600) {
+                throw new HTTPCodeNotHandledException($code);
+            }
+
+            if (class_exists($handler)) {
+                $reflection = new ReflectionClass($handler);
+                if (!$reflection->implementsInterface(ResponseHandler::class)) {
+                    throw new ErrorHandlerShouldImplementInterfaceException($code, $handler);
+                }
+            }
+        }
+    }
+}

include/Config/RouterConfiguration.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024-Present Kevin Traini
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Archict\Router\Config;
+
+/**
+ * @internal
+ */
+final readonly class RouterConfiguration
+{
+    /**
+     * @param array<int, string|class-string> $error_handling
+     */
+    public function __construct(
+        public array $error_handling = [],
+    ) {
+    }
+}

include/Exception/ErrorHandlerShouldImplementInterfaceException.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024-Present Kevin Traini
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Archict\Router\Exception;
+
+use Archict\Router\ResponseHandler;
+
+final class ErrorHandlerShouldImplementInterfaceException extends RouterException
+{
+    public function __construct(int $code, string $class)
+    {
+        parent::__construct("Error handler $class for code $code should implement interface " . ResponseHandler::class);
+    }
+}

include/Exception/HTTPCodeNotHandledException.php

@@ -0,0 +1,36 @@
+<?php
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024-Present Kevin Traini
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Archict\Router\Exception;
+
+final class HTTPCodeNotHandledException extends RouterException
+{
+    public function __construct(int $code)
+    {
+        parent::__construct("Error handling doesn't handle code $code");
+    }
+}

include/HTTP/ResponseHandler.php → include/HTTP/FinalResponseHandler.php

@@ -29,7 +29,10 @@
 
 use Psr\Http\Message\ResponseInterface;
 
-final class ResponseHandler
+/**
+ * @internal
+ */
+final class FinalResponseHandler
 {
     public function writeResponse(ResponseInterface $response): void
     {

include/ResponseHandler.php

@@ -0,0 +1,36 @@
+<?php
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024-Present Kevin Traini
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Archict\Router;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+interface ResponseHandler
+{
+    public function handleResponse(ResponseInterface $response, ServerRequestInterface $request): ResponseInterface;
+}