Add attributes support & improve MatchingResult

.phpstorm.meta.php/Group.php

@@ -11,9 +11,8 @@
         'host',
         'hosts',
         'corsMiddleware',
-        'items',
+        'routes',
         'middlewareDefinitions',
-        'hasDispatcher',
         'hasCorsMiddleware'
     );
-}
+}

.phpstorm.meta.php/Route.php

@@ -13,8 +13,7 @@
         'methods',
         'override',
         'defaults',
-        'dispatcherWithMiddlewares',
-        'hasDispatcher',
-        'hasMiddlewares'
+        'hasMiddlewares',
+        'builtMiddlewareDefinitions'
     );
-}
+}

CHANGELOG.md

@@ -5,6 +5,12 @@
 - New #195: Add debug collector for `yiisoft/yii-debug` (@xepozz)
 - Chg #207: Replace two `RouteCollectorInterface` methods `addRoute()` and `addGroup()` to single `addRoute()` (@vjik)
 - Enh #202: Add support for `psr/http-message` version `^2.0` (@vjik)
+- New #196: Add PHP Attributes support (@rustamwin)
+- New #196: Add `RoutesProviderInterface` interface providing routes from various resources (@rustamwin) 
+- Enh #196: The `Group` and `Route` classes have been refactored to be DTO objects & dispatcher-independent. (@rustamwin)
+- Enh #196: The `MatchingResult` class has been improved to be dispatcher-independent (@rustamwin)
+- Chg #196: The implementation of `MatchingResult` from `MiddlewareInterface` has been removed, so
+  it is no longer middleware. (@rustamwin)
 
 ## 3.0.0 February 17, 2023
 

README.md

@@ -29,6 +29,7 @@ with an adapter package. Currently, the only adapter available is [FastRoute](ht
 - Ready to use middleware for route matching.
 - Convenient `CurrentRoute` service that holds information about last matched route.
 - Out of the box CORS middleware support.
+- Declaring routes using PHP attributes.
 
 ## Requirements
 

src/Attribute/Delete.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Delete implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::DELETE],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Get.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Get implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::GET],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Head.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Head implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::HEAD],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Options.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Options implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::OPTIONS],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Patch.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Patch implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::PATCH],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Post.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Post implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::POST],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Put.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Put implements RouteAttributeInterface
+{
+    private Route $route;
+
+    /**
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param bool $override Marks route as override. When added it will replace existing route with the same name.
+     * @param array $disabledMiddlewares Excludes middleware from being invoked when action is handled.
+     * It is useful to avoid invoking one of the parent group middleware for
+     * a certain route.
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = []
+    ) {
+        $this->route = new Route(
+            methods: [Method::PUT],
+            pattern: $pattern,
+            name: $name,
+            middlewareDefinitions: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewareDefinitions: $disabledMiddlewares
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}