Merge pull request #56 from sunrise-php/release/v2.4.0

v2.4.0
sunrise-php · Apr 20, 2020 · 2b5089a · 2b5089a
2 parents f3ac5e9 + de81569
commit 2b5089a
Show file tree

Hide file tree

Showing 19 changed files with 568 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 ## Installation
 
 ```bash
-composer require 'sunrise/http-router:^2.2'
+composer require 'sunrise/http-router:^2.4'
 ```
 
 ## QuickStart
@@ -70,6 +70,14 @@ $loader->attach('routes/public.php');
 // [!] available from version 2.2
 $loader->attach('routes');
 
+// or attach an array...
+// [!] available from version 2.4
+$loader->attachArray([
+    'routes/api.php',
+    'routes/admin.php',
+    'routes/public.php',
+]);
+
 $router = new Router();
 $router->load($loader);
 
@@ -92,6 +100,13 @@ AnnotationRegistry::registerLoader('class_exists');
 $loader = new AnnotationDirectoryLoader();
 $loader->attach('src/Controller');
 
+// or attach an array
+// [!] available from version 2.4
+$loader->attachArray([
+    'src/Controller',
+    'src/Bundle/BundleName/Controller',
+]);
+
 $router = new Router();
 $router->load($loader);
 
@@ -122,6 +137,29 @@ $response = $router->handle($request);
 $response = $router->process($request, $handler);
 ```
 
+#### Route Annotation Example
+
+```php
+/**
+ * @Route(
+ *   name="apiEntryUpdate",
+ *   path="/api/v1/entry/{id<@uuid>}(/{optionalAttribute})",
+ *   methods={"PATCH"},
+ *   middlewares={
+ *     "App\Middleware\CorsMiddleware",
+ *     "App\Middleware\ApiAuthMiddleware",
+ *   },
+ *   attributes={
+ *     "optionalAttribute": "defaultValue",
+ *   },
+ *   summary="Updates an entry by UUID",
+ *   description="Here you can describe the method in more detail...",
+ *   tags={"api", "entry"},
+ *   priority=0,
+ * )
+ */
+```
+
 ---
 
 ## Useful to know

diff --git a/src/Annotation/Route.php b/src/Annotation/Route.php
@@ -60,6 +60,27 @@ final class Route
      */
     public $attributes;
 
+    /**
+     * @var string
+     *
+     * @since 2.4.0
+     */
+    public $summary;
+
+    /**
+     * @var string
+     *
+     * @since 2.4.0
+     */
+    public $description;
+
+    /**
+     * @var array
+     *
+     * @since 2.4.0
+     */
+    public $tags;
+
     /**
      * @var int
      */
@@ -73,6 +94,9 @@ public function __construct(array $params)
         $params += [
             'middlewares' => [],
             'attributes' => [],
+            'summary' => '',
+            'description' => '',
+            'tags' => [],
             'priority' => 0,
         ];
 
@@ -81,13 +105,19 @@ public function __construct(array $params)
         $this->assertParamsContainValidMethods($params);
         $this->assertParamsContainValidMiddlewares($params);
         $this->assertParamsContainValidAttributes($params);
+        $this->assertParamsContainValidSummary($params);
+        $this->assertParamsContainValidDescription($params);
+        $this->assertParamsContainValidTags($params);
         $this->assertParamsContainValidPriority($params);
 
         $this->name = $params['name'];
         $this->path = $params['path'];
         $this->methods = $params['methods'];
         $this->middlewares = $params['middlewares'];
         $this->attributes = $params['attributes'];
+        $this->summary = $params['summary'];
+        $this->description = $params['description'];
+        $this->tags = $params['tags'];
         $this->priority = $params['priority'];
     }
 
@@ -209,6 +239,62 @@ private function assertParamsContainValidAttributes(array $params) : void
         }
     }
 
+    /**
+     * @param array $params
+     *
+     * @return void
+     *
+     * @throws InvalidAnnotationParameterException
+     */
+    private function assertParamsContainValidSummary(array $params) : void
+    {
+        if (!is_string($params['summary'])) {
+            throw new InvalidAnnotationParameterException(
+                '@Route.summary must be a string.'
+            );
+        }
+    }
+
+    /**
+     * @param array $params
+     *
+     * @return void
+     *
+     * @throws InvalidAnnotationParameterException
+     */
+    private function assertParamsContainValidDescription(array $params) : void
+    {
+        if (!is_string($params['description'])) {
+            throw new InvalidAnnotationParameterException(
+                '@Route.description must be a string.'
+            );
+        }
+    }
+
+    /**
+     * @param array $params
+     *
+     * @return void
+     *
+     * @throws InvalidAnnotationParameterException
+     */
+    private function assertParamsContainValidTags(array $params) : void
+    {
+        if (!is_array($params['tags'])) {
+            throw new InvalidAnnotationParameterException(
+                '@Route.tags must be an array.'
+            );
+        }
+
+        foreach ($params['tags'] as $middleware) {
+            if (!is_string($middleware)) {
+                throw new InvalidAnnotationParameterException(
+                    '@Route.tags must contain only strings.'
+                );
+            }
+        }
+    }
+
     /**
      * @param array $params
      *

diff --git a/src/Exception/MethodNotAllowedException.php b/src/Exception/MethodNotAllowedException.php
@@ -11,6 +11,11 @@
 
 namespace Sunrise\Http\Router\Exception;
 
+/**
+ * Import functions
+ */
+use function implode;
+
 /**
  * MethodNotAllowedException
  */
@@ -26,4 +31,14 @@ public function getAllowedMethods() : array
     {
         return $this->fromContext('allowed', []);
     }
+
+    /**
+     * Gets joined allowed methods
+     *
+     * @return string
+     */
+    public function getJoinedAllowedMethods() : string
+    {
+        return implode(',', $this->getAllowedMethods());
+    }
 }
diff --git a/src/Exception/UnsupportedMediaTypeException.php b/src/Exception/UnsupportedMediaTypeException.php
@@ -11,6 +11,11 @@
 
 namespace Sunrise\Http\Router\Exception;
 
+/**
+ * Import functions
+ */
+use function implode;
+
 /**
  * UnsupportedMediaTypeException
  */
@@ -36,4 +41,14 @@ public function getSupportedTypes() : array
     {
         return $this->fromContext('supported', []);
     }
+
+    /**
+     * Gets joined supported types
+     *
+     * @return string
+     */
+    public function getJoinedSupportedTypes() : string
+    {
+        return implode(',', $this->getSupportedTypes());
+    }
 }
diff --git a/src/Loader/AnnotationDirectoryLoader.php b/src/Loader/AnnotationDirectoryLoader.php
@@ -152,6 +152,16 @@ public function attach($resource) : void
         $this->resources[] = $resource;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function attachArray(array $resources) : void
+    {
+        foreach ($resources as $resource) {
+            $this->attach($resource);
+        }
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -171,7 +181,10 @@ public function load() : RouteCollectionInterface
                 $this->initClass($class),
                 $this->initClasses(...$annotation->middlewares),
                 $annotation->attributes
-            );
+            )
+            ->setSummary($annotation->summary)
+            ->setDescription($annotation->description)
+            ->setTags(...$annotation->tags);
         }
 
         return $this->collectionFactory->createCollection(...$routes);

diff --git a/src/Loader/CollectableFileLoader.php b/src/Loader/CollectableFileLoader.php
@@ -89,6 +89,16 @@ public function attach($resource) : void
         $this->resources[] = $resource;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function attachArray(array $resources) : void
+    {
+        foreach ($resources as $resource) {
+            $this->attach($resource);
+        }
+    }
+
     /**
      * {@inheritDoc}
      */

diff --git a/src/Loader/LoaderInterface.php b/src/Loader/LoaderInterface.php
@@ -34,6 +34,17 @@ interface LoaderInterface
      */
     public function attach($resource) : void;
 
+    /**
+     * Attaches the given array with resources to the loader
+     *
+     * @param array $resources
+     *
+     * @return void
+     *
+     * @throws InvalidLoaderResourceException
+     */
+    public function attachArray(array $resources) : void;
+
     /**
      * Loads routes from previously attached resources
      *