Merge pull request #95 from sunrise-php/release/v2.14.0

v2.14.0

Author: fenric

CHANGELOG.md

@@ -1,3 +1,10 @@
 ## v2.13.0
 
 * Supports for events using the `symfony/event-dispatcher`.
+
+## v2.14.0
+
+* New method added: `Route::getHolder():Reflector`;
+* New method added: `Router::resolveHostname(string):?string`;
+* New method added: `Router::getRoutesByHostname(string):array`;
+* New method added: `RouterBuilder::setEventDispatcher(?EventDispatcherInterface):void`.

README.md

@@ -12,7 +12,7 @@
 ## Installation
 
 ```bash
-composer require 'sunrise/http-router:^2.13'
+composer require 'sunrise/http-router:^2.14'
 ```
 
 ## Support for OpenAPI (Swagger) Specification (optional)
@@ -444,6 +444,28 @@ use Sunrise\Http\Router\Annotation\Route;
 final class EntryUpdateRequestHandler implements RequestHandlerInterface
 ```
 
+##### Additional annotations
+
+```php
+use Sunrise\Http\Router\Annotation\Host;
+
+#[Host('admin')]
+#[Prefix('/api/v1')]
+#[Postfix('.json')]
+#[Middleware(SomeMiddleware::class)]
+final class SomeController
+{
+    #[Route('foo', '/foo')]
+    public function foo(ServerRequestInterface $request) : ResponseInterface
+    {
+        // this action will be available at:
+        // http://admin.host/api/v1/foo.json
+        //
+        // this can be handy to reduce code duplication...
+    }
+}
+```
+
 ---
 
 ## Useful to know
@@ -469,6 +491,16 @@ $request->getAttribute('@route');
 $request->getAttribute(\Sunrise\Http\Router\RouteInterface::ATTR_ROUTE);
 ```
 
+#### Through Event
+
+> Available from version 2.13.
+
+```php
+$eventDispatcher->addListener(RouteEvent::NAME, function (RouteEvent $event) {
+    $event->getRoute();
+});
+```
+
 ### Generation a route URI
 
 ```php
@@ -485,6 +517,8 @@ $response = $router->getRoute('route.name')->handle($request);
 
 ### Route grouping
 
+Example for annotations [here](#additional-annotations).
+
 ```php
 $collector->group(function ($collector) {
     $collector->group(function ($collector) {
@@ -528,15 +562,39 @@ $collector->get('api.entry.read', '/api/v1/entry/{slug<@slug>}');
 $collector->get('api.entry.read', '/api/v1/entry/{id<@id>}');
 ```
 
+It is better to set patterns through the router:
+
+```php
+// available since version 2.11.0
+$router->addPatterns([
+    '@id' => '[1-9][0-9]*',
+]);
+```
+
+...or through the router's builder:
+
+```php
+// available since version 2.11.0
+$builder->setPatterns([
+    '@id' => '[1-9][0-9]*',
+]);
+```
+
 ### Hosts (available from version 2.6.0)
 
 > Note: if you don't assign a host for a route, it will be available on any hosts!
 
 ```php
 // move the hosts table into the settings...
-$router->addHost('public.host', 'www.example.com');
-$router->addHost('admin.host', 'secret.example.com');
-$router->addHost('api.host', 'api.example.com');
+$router->addHost('public.host', 'www.example.com', ...);
+$router->addHost('admin.host', 'secret.example.com', ...);
+$router->addHost('api.host', 'api.example.com', ...);
+
+// ...or:
+$router->addHosts([
+    'public.host' => ['www.example.com', ...],
+    ...
+]);
 
 // the route will available only on the `secret.example.com` host...
 $route->setHost('admin.host');
@@ -548,6 +606,28 @@ $collector->group(function ($collector) {
 ->setHost('admin.host');
 ```
 
+You can resolve the hostname since version 2.14.0 as follows:
+
+```php
+$router->addHost('admin', 'www1.admin.example.com', 'www2.admin.example.com');
+
+$router->resolveHostname('www1.admin.example.com'); // return "admin"
+$router->resolveHostname('www2.admin.example.com'); // return "admin"
+$router->resolveHostname('unknown'); // return null
+```
+
+Also you can get all routes by hostname:
+
+```php
+$router->getRoutesByHostname('www1.admin.example.com');
+```
+
+### Route Holder
+
+```php
+$route->getHolder(); // return Reflector (class, method or function)
+```
+
 ### The router builder
 
 ```php
@@ -559,6 +639,7 @@ $router = (new RouterBuilder)
     ->useDescriptorLoader([]) // array with classes or directory with classes...
     ->setHosts([]) //
     ->setMiddlewares([]) // array with middlewares...
+    ->setPatterns([]) // available since version 2.11.0
     ->build();
 ```
 

src/Command/RouteListCommand.php

@@ -47,6 +47,8 @@ class RouteListCommand extends Command
 
     /**
      * {@inheritdoc}
+     *
+     * @var string
      */
     protected static $defaultDescription = 'Lists all routes in your application';
 

src/Loader/ConfigLoader.php

@@ -108,9 +108,9 @@ public function setContainer(?ContainerInterface $container) : void
     public function attach($resource) : void
     {
         if (is_dir($resource)) {
-            $resources = glob($resource . '/*.php');
-            foreach ($resources as $resource) {
-                $this->resources[] = $resource;
+            $fileNames = glob($resource . '/*.php');
+            foreach ($fileNames as $fileName) {
+                $this->resources[] = $fileName;
             }
 
             return;

src/Loader/DescriptorLoader.php

@@ -16,6 +16,7 @@
  */
 use Doctrine\Common\Annotations\SimpleAnnotationReader;
 use Psr\Container\ContainerInterface;
+use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 use Psr\SimpleCache\CacheInterface;
 use Sunrise\Http\Router\Annotation\Host;
@@ -61,7 +62,7 @@ class DescriptorLoader implements LoaderInterface
 {
 
     /**
-     * @var string[]
+     * @var class-string[]
      */
     private $resources = [];
 
@@ -194,9 +195,9 @@ public function setCacheKey(?string $cacheKey) : void
     public function attach($resource) : void
     {
         if (is_dir($resource)) {
-            $resources = $this->scandir($resource);
-            foreach ($resources as $resource) {
-                $this->resources[] = $resource;
+            $classNames = $this->scandir($resource);
+            foreach ($classNames as $className) {
+                $this->resources[] = $className;
             }
 
             return;
@@ -234,9 +235,9 @@ public function load() : RouteCollectionInterface
 
         $routes = [];
         foreach ($descriptors as $descriptor) {
-            $middlewares = $descriptor->middlewares;
-            foreach ($middlewares as &$middleware) {
-                $middleware = $this->referenceResolver->toMiddleware($middleware);
+            $middlewares = [];
+            foreach ($descriptor->middlewares as $className) {
+                $middlewares[] = $this->referenceResolver->toMiddleware($className);
             }
 
             $routes[] = $this->routeFactory->createRoute(
@@ -403,7 +404,7 @@ private function supplementDescriptor(Route $descriptor, Reflector $reflector) :
      * @param ReflectionClass|ReflectionMethod $reflector
      * @param class-string<T> $annotationName
      *
-     * @return array<T>
+     * @return T[]
      *
      * @template T
      */
@@ -438,7 +439,7 @@ private function getAnnotations(Reflector $reflector, string $annotationName) :
      *
      * @param string $directory
      *
-     * @return string[]
+     * @return class-string[]
      */
     private function scandir(string $directory) : array
     {

src/ReferenceResolver.php

@@ -126,15 +126,19 @@ public function toMiddleware($reference) : MiddlewareInterface
      *
      * @param mixed $reference
      *
-     * @return array
+     * @return array{0: ?class-string, 1: ?string}
      */
     private function normalizeReference($reference) : array
     {
         if (is_array($reference) && is_callable($reference, true)) {
+            /** @var array{0: class-string, 1: string} $reference */
+
             return $reference;
         }
 
         if (is_string($reference)) {
+            /** @var class-string $reference */
+
             return [$reference, null];
         }
 

src/Route.php

@@ -18,7 +18,13 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
+use Sunrise\Http\Router\RequestHandler\CallableRequestHandler;
 use Sunrise\Http\Router\RequestHandler\QueueableRequestHandler;
+use Closure;
+use ReflectionClass;
+use ReflectionMethod;
+use ReflectionFunction;
+use Reflector;
 
 /**
  * Import functions
@@ -228,6 +234,26 @@ public function getTags() : array
         return $this->tags;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function getHolder() : Reflector
+    {
+        $handler = $this->requestHandler;
+        if ($handler instanceof CallableRequestHandler) {
+            $callback = $handler->getCallback();
+            if ($callback instanceof Closure) {
+                return new ReflectionFunction($callback);
+            }
+
+            /** @var array{0: class-string|object, 1: string} $callback */
+
+            return new ReflectionMethod(...$callback);
+        }
+
+        return new ReflectionClass($handler);
+    }
+
     /**
      * {@inheritdoc}
      */

src/RouteInterface.php

@@ -16,6 +16,10 @@
  */
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
+use ReflectionClass;
+use ReflectionMethod;
+use ReflectionFunction;
+use Reflector;
 
 /**
  * RouteInterface
@@ -110,6 +114,15 @@ public function getDescription() : string;
      */
     public function getTags() : array;
 
+    /**
+     * Gets the route holder
+     *
+     * @return ReflectionClass|ReflectionMethod|ReflectionFunction
+     *
+     * @since 2.14.0
+     */
+    public function getHolder() : Reflector;
+
     /**
      * Sets the given name to the route
      *