Merge pull request #70 from sunrise-php/release/v2.8.0

v2.8.0

Author: fenric

README.md

@@ -12,7 +12,7 @@
 ## Installation
 
 ```bash
-composer require 'sunrise/http-router:^2.6'
+composer require 'sunrise/http-router:^2.8'
 ```
 
 ## QuickStart
@@ -81,13 +81,26 @@ $loader->attachArray([
 $router = new Router();
 $router->load($loader);
 
+// if the router matching should be isolated for top middlewares...
+// for example for error handling...
+// [!] available from version 2.8
+$response = $router->run($request);
+
 // if the router is used as a request handler
 $response = $router->handle($request);
 
 // if the router is used as middleware
 $response = $router->process($request, $handler);
 ```
 
+```php
+/** @var Sunrise\Http\Router\RouteCollector $this */
+
+$this->get('home', '/', new CallableRequestHandler(function ($request) {
+    return (new ResponseFactory)->createJsonResponse(200);
+}));
+```
+
 #### Strategy loading routes from descriptors (annotations or attributes)
 
 ```php
@@ -111,6 +124,11 @@ $loader->attachArray([
 $router = new Router();
 $router->load($loader);
 
+// if the router matching should be isolated for top middlewares...
+// for example for error handling...
+// [!] available from version 2.8
+$response = $router->run($request);
+
 // if the router is used as a request handler
 $response = $router->handle($request);
 
@@ -131,13 +149,56 @@ $collector->get('home', '/', new HomeController());
 $router = new Router();
 $router->addRoute(...$collector->getCollection()->all());
 
+// if the router matching should be isolated for top middlewares...
+// for example for error handling...
+// [!] available from version 2.8
+$response = $router->run($request);
+
 // if the router is used as a request handler
 $response = $router->handle($request);
 
 // if the router is used as middleware
 $response = $router->process($request, $handler);
 ```
 
+#### Error handling example
+
+```php
+use Sunrise\Http\Message\ResponseFactory;
+use Sunrise\Http\Router\Exception\MethodNotAllowedException;
+use Sunrise\Http\Router\Exception\RouteNotFoundException;
+use Sunrise\Http\Router\Middleware\CallableMiddleware;
+use Sunrise\Http\Router\RequestHandler\CallableRequestHandler;
+use Sunrise\Http\Router\RouteCollector;
+use Sunrise\Http\Router\Router;
+use Sunrise\Http\ServerRequest\ServerRequestFactory;
+
+use function Sunrise\Http\Router\emit;
+
+$collector = new RouteCollector();
+
+$collector->get('home', '/', new CallableRequestHandler(function ($request) {
+    return (new ResponseFactory)->createJsonResponse(200);
+}));
+
+$router = new Router();
+$router->addRoute(...$collector->getCollection()->all());
+
+$router->addMiddleware(new CallableMiddleware(function ($request, $handler) {
+    try {
+        return $handler->handle($request);
+    } catch (MethodNotAllowedException $e) {
+        return (new ResponseFactory)->createResponse(405);
+    } catch (RouteNotFoundException $e) {
+        return (new ResponseFactory)->createResponse(404);
+    } catch (Throwable $e) {
+        return (new ResponseFactory)->createResponse(500);
+    }
+}));
+
+emit($router->run(ServerRequestFactory::fromGlobals()));
+```
+
 #### Route Annotation Example
 
 ##### Minimal annotation view

composer.json

@@ -60,8 +60,8 @@
     },
     "scripts": {
         "test": [
-            "phpunit --colors=always --coverage-text",
-            "phpcs"
+            "phpcs",
+            "XDEBUG_MODE=coverage phpunit --colors=always --coverage-text"
         ],
         "bench": [
             "phpbench run --report='generator: \"table\", cols: [\"groups\", \"subject\", \"mean\", \"diff\"], sort: {mean: \"asc\"}'"

src/Middleware/CallableMiddleware.php

@@ -0,0 +1,54 @@
+<?php declare(strict_types=1);
+
+/**
+ * It's free open-source software released under the MIT License.
+ *
+ * @author Anatoly Fenric <[email protected]>
+ * @copyright Copyright (c) 2018, Anatoly Fenric
+ * @license https://github.com/sunrise-php/http-router/blob/master/LICENSE
+ * @link https://github.com/sunrise-php/http-router
+ */
+
+namespace Sunrise\Http\Router\Middleware;
+
+/**
+ * Import classes
+ */
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+/**
+ * CallableMiddleware
+ *
+ * @since 2.8.0
+ */
+class CallableMiddleware implements MiddlewareInterface
+{
+
+    /**
+     * The middleware callback
+     *
+     * @var callable
+     */
+    private $callback;
+
+    /**
+     * Constructor of the class
+     *
+     * @param callable $callback
+     */
+    public function __construct(callable $callback)
+    {
+        $this->callback = $callback;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler) : ResponseInterface
+    {
+        return ($this->callback)($request, $handler);
+    }
+}

src/Router.php

@@ -24,6 +24,7 @@
 use Sunrise\Http\Router\Exception\RouteAlreadyExistsException;
 use Sunrise\Http\Router\Exception\RouteNotFoundException;
 use Sunrise\Http\Router\Loader\LoaderInterface;
+use Sunrise\Http\Router\RequestHandler\CallableRequestHandler;
 use Sunrise\Http\Router\RequestHandler\QueueableRequestHandler;
 
 /**
@@ -275,6 +276,28 @@ public function match(ServerRequestInterface $request) : RouteInterface
         throw new RouteNotFoundException('Route Not Found');
     }
 
+    /**
+     * Runs the router
+     *
+     * @param ServerRequestInterface $request
+     *
+     * @return ResponseInterface
+     *
+     * @since 2.8.0
+     */
+    public function run(ServerRequestInterface $request) : ResponseInterface
+    {
+        // lazy resolving of the given request...
+        $routing = new CallableRequestHandler(function (ServerRequestInterface $request) : ResponseInterface {
+            return $this->match($request)->handle($request);
+        });
+
+        $handler = new QueueableRequestHandler($routing);
+        $handler->add(...$this->getMiddlewares());
+
+        return $handler->handle($request);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -295,7 +318,7 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
     {
         try {
             return $this->handle($request);
-        } catch (MethodNotAllowedException | RouteNotFoundException $e) {
+        } catch (MethodNotAllowedException|RouteNotFoundException $e) {
             $request = $request->withAttribute(self::ATTR_NAME_FOR_ROUTING_ERROR, $e);
 
             return $handler->handle($request);

tests/Middleware/CallableMiddlewareTest.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types=1);
+
+namespace Sunrise\Http\Router\Tests\Middleware;
+
+/**
+ * Import classes
+ */
+use PHPUnit\Framework\TestCase;
+use Psr\Http\Server\MiddlewareInterface;
+use Sunrise\Http\Router\Middleware\CallableMiddleware;
+use Sunrise\Http\Router\Tests\Fixture;
+use Sunrise\Http\ServerRequest\ServerRequestFactory;
+
+/**
+ * CallableMiddlewareTest
+ */
+class CallableMiddlewareTest extends TestCase
+{
+
+    /**
+     * @return void
+     */
+    public function testContracts() : void
+    {
+        $middleware = new CallableMiddleware(function ($request, $handler) {
+            return $handler->handle($request);
+        });
+
+        $this->assertInstanceOf(MiddlewareInterface::class, $middleware);
+    }
+
+    /**
+     * @return void
+     */
+    public function testRun() : void
+    {
+        $middleware = new CallableMiddleware(function ($request, $handler) {
+            return $handler->handle($request);
+        });
+
+        $request = (new ServerRequestFactory)->createServerRequest('GET', '/');
+        $requestHandler = new Fixture\BlankRequestHandler();
+        $middleware->process($request, $requestHandler);
+
+        $this->assertTrue($requestHandler->isRunned());
+    }
+}

tests/RouterTest.php

@@ -12,10 +12,12 @@
 use Sunrise\Http\Router\Exception\MiddlewareAlreadyExistsException;
 use Sunrise\Http\Router\Exception\RouteAlreadyExistsException;
 use Sunrise\Http\Router\Exception\RouteNotFoundException;
+use Sunrise\Http\Router\Middleware\CallableMiddleware;
 use Sunrise\Http\Router\Loader\LoaderInterface;
 use Sunrise\Http\Router\Route;
 use Sunrise\Http\Router\RouteCollection;
 use Sunrise\Http\Router\Router;
+use Sunrise\Http\Message\ResponseFactory;
 use Sunrise\Http\ServerRequest\ServerRequestFactory;
 
 /**
@@ -299,6 +301,84 @@ public function testMatchForUndefinedRoute() : void
         }
     }
 
+    /**
+     * @return void
+     */
+    public function testRun() : void
+    {
+        $routes = [
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+        ];
+
+        $router = new Router();
+        $router->addRoute(...$routes);
+        $router->run((new ServerRequestFactory)
+            ->createServerRequest(
+                $routes[1]->getMethods()[1],
+                $routes[1]->getPath()
+            ));
+
+        $this->assertTrue($routes[1]->getRequestHandler()->isRunned());
+    }
+
+    /**
+     * @return void
+     */
+    public function testRunWithNotAllowedMethod() : void
+    {
+        $routes = [
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+        ];
+
+        $router = new Router();
+        $router->addRoute(...$routes);
+
+        $router->addMiddleware(new CallableMiddleware(function ($request, $handler) {
+            try {
+                return $handler->handle($request);
+            } catch (MethodNotAllowedException $e) {
+                return (new ResponseFactory)->createResponse(405);
+            }
+        }));
+
+        $response = $router->run((new ServerRequestFactory)
+            ->createServerRequest('UNKNOWN', $routes[1]->getPath()));
+
+        $this->assertSame(405, $response->getStatusCode());
+    }
+
+    /**
+     * @return void
+     */
+    public function testRunWithNotFoundRoute() : void
+    {
+        $routes = [
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+            new Fixture\TestRoute(),
+        ];
+
+        $router = new Router();
+        $router->addRoute(...$routes);
+
+        $router->addMiddleware(new CallableMiddleware(function ($request, $handler) {
+            try {
+                return $handler->handle($request);
+            } catch (RouteNotFoundException $e) {
+                return (new ResponseFactory)->createResponse(404);
+            }
+        }));
+
+        $response = $router->run((new ServerRequestFactory)
+            ->createServerRequest($routes[1]->getMethods()[1], '/unknown'));
+
+        $this->assertSame(404, $response->getStatusCode());
+    }
+
     /**
      * @return void
      */