Add attributes support

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 4.0.3 under development
 
+- New #196: Add PHP Attributes support (@rustamwin)
+- New #196: Add `RoutesProviderInterface` interface providing routes from various resources (@rustamwin)
+- Bug #196: Fix the behavior of `Group::hosts()` method to be consistent with `Route::hosts()` method (@rustamwin)
+- Chg #196: Make constructor of `Route` and `Group` classes public (@rustamwin)
+- Chg #196: Deprecate static methods of `Route` and `Group` classes (@rustamwin)
 - Enh #276: Explicitly import classes, functions, and constants in the "use" section (@rustamwin)
 - Enh #277, #281: Remove restrictions from `prependMiddleware()` and `middleware()` methods (@klsoft-web, @vjik)
 

README.md

@@ -28,6 +28,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
 
@@ -45,7 +46,7 @@ Additionally, you will need an adapter such as [FastRoute](https://github.com/yi
 
 ## Defining routes and URL matching
 
-Common usage of the router looks like the following:
+#### Common usage of the router looks like the following
 
 ```php
 use Yiisoft\Router\CurrentRoute;
@@ -101,6 +102,36 @@ if (!$result->isSuccess()) {
 $response = $result->process($request, $notFoundHandler);
 ```
 
+#### Using attributes is also supported
+
+In controller:
+
+```php
+use Yiisoft\Router\Attribute\Get;
+
+final class SiteController
+{
+    //...
+
+    #[Get('/')]
+    public function home(ServerRequestInterface $request): ResponseInterface
+    {
+        return $this->responseFactory->createResponse()->withBody(
+            $this->streamFactory->createStream('You are at homepage.')
+        );
+    }
+
+    #[Get('/test/{id:\w+}')]
+    public function test(CurrentRoute $currentRoute): ResponseInterface
+    {
+        $id = $currentRoute->getArgument('id');
+
+        return $this->responseFactory->createResponse()->withBody(
+            $this->streamFactory->createStream('You are at test with argument ' . $id)
+        );
+}
+```
+
 > Note: Despite `UrlGeneratorInterface` and `UrlMatcherInterface` being common for all adapters available, certain
 > features and, especially, pattern syntax may differ. To check usage and configuration details, please refer
 > to specific adapter documentation. All examples in this document are for

src/Attribute/Delete.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+/**
+ * Route attribute that defines a DELETE HTTP method route.
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Delete implements RouteAttributeInterface
+{
+    private readonly Route $route;
+
+    /**
+     * @param string $pattern Route pattern.
+     * @param string|null $name Route name.
+     * @param array[]|callable[]|string[] $middlewares Middlewares to be added to the route.
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param string[] $hosts Hosts that the route should match.
+     * @param bool $override Marks route as override. When added, it will replace the 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.
+     *
+     * @psalm-param list<array|callable|string> $middlewares
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = [],
+    ) {
+        $this->route = new Route(
+            method: [Method::DELETE],
+            pattern: $pattern,
+            name: $name,
+            middlewares: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewares: $disabledMiddlewares,
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Get.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+/**
+ * Route attribute that defines a GET HTTP method route.
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Get implements RouteAttributeInterface
+{
+    private readonly Route $route;
+
+    /**
+     * @param string $pattern Route pattern.
+     * @param string|null $name Route name.
+     * @param array[]|callable[]|string[] $middlewares Middlewares to be added to the route.
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param string[] $hosts Hosts that the route should match.
+     * @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.
+     *
+     * @psalm-param list<array|callable|string> $middlewares
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = [],
+    ) {
+        $this->route = new Route(
+            method: [Method::GET],
+            pattern: $pattern,
+            name: $name,
+            middlewares: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewares: $disabledMiddlewares,
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Head.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+/**
+ * Route attribute that defines a HEAD HTTP method route.
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Head implements RouteAttributeInterface
+{
+    private readonly Route $route;
+
+    /**
+     * @param string $pattern Route pattern.
+     * @param string|null $name Route name.
+     * @param array[]|callable[]|string[] $middlewares Middlewares to be added to the route.
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param string[] $hosts Hosts that the route should match.
+     * @param bool $override Marks route as override. When added, it will replace the 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.
+     *
+     * @psalm-param list<array|callable|string> $middlewares
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = [],
+    ) {
+        $this->route = new Route(
+            method: [Method::HEAD],
+            pattern: $pattern,
+            name: $name,
+            middlewares: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewares: $disabledMiddlewares,
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Options.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+/**
+ * Route attribute that defines an OPTIONS HTTP method route.
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Options implements RouteAttributeInterface
+{
+    private readonly Route $route;
+
+    /**
+     * @param string $pattern Route pattern.
+     * @param string|null $name Route name.
+     * @param array[]|callable[]|string[] $middlewares Middlewares to be added to the route.
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param string[] $hosts Hosts that the route should match.
+     * @param bool $override Marks route as override. When added, it will replace the 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.
+     *
+     * @psalm-param list<array|callable|string> $middlewares
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = [],
+    ) {
+        $this->route = new Route(
+            method: [Method::OPTIONS],
+            pattern: $pattern,
+            name: $name,
+            middlewares: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewares: $disabledMiddlewares,
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}

src/Attribute/Patch.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Router\Attribute;
+
+use Attribute;
+use Stringable;
+use Yiisoft\Http\Method;
+use Yiisoft\Router\Route;
+
+/**
+ * Route attribute that defines a PATCH HTTP method route.
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final class Patch implements RouteAttributeInterface
+{
+    private readonly Route $route;
+
+    /**
+     * @param string $pattern Route pattern.
+     * @param string|null $name Route name.
+     * @param array[]|callable[]|string[] $middlewares Middlewares to be added to the route.
+     * @param array<string,scalar|Stringable|null> $defaults Parameter default values indexed by parameter names.
+     * @param string[] $hosts Hosts that the route should match.
+     * @param bool $override Marks route as override. When added, it will replace the 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.
+     *
+     * @psalm-param list<array|callable|string> $middlewares
+     */
+    public function __construct(
+        string $pattern,
+        ?string $name = null,
+        array $middlewares = [],
+        array $defaults = [],
+        array $hosts = [],
+        bool $override = false,
+        array $disabledMiddlewares = [],
+    ) {
+        $this->route = new Route(
+            method: [Method::PATCH],
+            pattern: $pattern,
+            name: $name,
+            middlewares: $middlewares,
+            defaults: $defaults,
+            hosts: $hosts,
+            override: $override,
+            disabledMiddlewares: $disabledMiddlewares,
+        );
+    }
+
+    public function getRoute(): Route
+    {
+        return $this->route;
+    }
+}