feat(router)!: add route decorators (#1695)

Author: brendt

docs/1-essentials/01-routing.md

@@ -440,26 +440,120 @@ final readonly class ReceiveInteractionController
 }
 ```
 
-### Group middleware
+## Route decorators (route groups)
 
-While Tempest does not provide a way to group middleware, you can easily create your own route attribute that applies or excludes a set of middleware to a route.
+Route decorators are Tempest's way to manage routes in bulk; it's a feature similar to route groups in other frameworks. Route decorators are attributes that implement the {b`\Tempest\Router\RouteDecorator`} interface. A route decorator's task is to make changes or add functionality to whether route it's associated with. Tempest comes with a few built-in route decorators, and you can make your own as well.
 
-```php Api.php
-#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Api implements Route
+In most cases, you'll want to add route decorators to a controller class, so that they are applied to all actions of that class:
+
+```php
+use Tempest\Router\Prefix;
+use Tempest\Router\Get;
+
+#[Prefix('/api')]
+final readonly class ApiController
 {
-    public function __construct(
-        public Method $method,
-        public string $uri,
-        public array $middleware = [],
-        public array $without = [],
-    ) {
-        $this->uri = "/api/{$uri}";
-        $this->without[] = [
-            ...$without,
-            VerifyCsrfMiddleware::class,
-            SetCookieMiddleware::class
-        ];
+    #[Get('/books')]
+    public function books(): Response { /* … */ }
+    
+    #[Get('/authors')]
+    public function authors(): Response { /* … */ }
+}
+```
+
+However, route decorators may also be applied to individual controller actions:
+
+```php
+use Tempest\Router\Stateless;
+use Tempest\Router\Get;
+
+final readonly class BlogPostController
+{
+    #[Stateless]
+    #[Get('/rss')]
+    public function rss(): Response { /* … */ }
+}
+```
+
+### Built-in route decorators
+
+These route decorators are provided by Tempest:
+
+#### `#[Stateless]`
+
+When you're building API endpoints, RSS feeds, or any other kind of page that does not require any cookie or session data, you may use the {b`#[Tempest\Router\Stateless]`} attribute, which will remove all state-related logic:
+
+```php
+use Tempest\Router\Stateless;
+use Tempest\Router\Get;
+
+final readonly class BlogPostController
+{
+    #[Stateless]
+    #[Get('/rss')]
+    public function rss(): Response { /* … */ }
+}
+```
+
+#### `#[Prefix]`
+
+Adds a prefix to all associated routes.
+
+```php
+use Tempest\Router\Prefix;
+use Tempest\Router\Get;
+
+#[Prefix('/api')]
+final readonly class ApiController
+{
+    #[Get('/books')]
+    public function books(): Response { /* … */ }
+    
+    #[Get('/authors')]
+    public function authors(): Response { /* … */ }
+}
+```
+
+#### `#[WithMiddleware]`
+
+Adds middleware to all associated routes.
+
+```php
+use Tempest\Router\WithMiddleware;
+use Tempest\Router\Get;
+
+#[Middleware(AuthMiddleware::class, AdminMiddleware::class)]
+final readonly class AdminController { /* … */ }
+```
+
+#### `#[WithoutMiddleware]`
+
+Explicitly removes middleware to all associated routes.
+
+```php
+use Tempest\Router\WithoutMiddleware;
+use Tempest\Router\Get;
+
+#[WithoutMiddleware(VerifyCsrfMiddleware::class, SetCookieMiddleware::class)]
+final readonly class StatelessController { /* … */ }
+```
+
+### Custom route decorators
+
+Building your own route decorators is done by implementing the {b`\Tempest\Router\RouteDecorator`} interface and marking your decorator as an attribute.
+
+```php
+use Attribute;
+use Tempest\Router\RouteDecorator;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
+final readonly class Auth implements RouteDecorator
+{
+    public function decorate(Route $route): Route
+    {
+        $route->middleare[] = AuthMiddleware::class;
+
+        return $route;
     }
 }
 ```
@@ -631,23 +725,6 @@ final class ErrorResponseProcessor implements ResponseProcessor
 }
 ```
 
-## Stateless routes
-
-When you're building API endpoints, RSS pages, or any other kind of page that does not require any cookie or session data, you may use the `{#[Tempest\Router\Stateless]}` attribute, which will remove all state-related logic:
-
-```php
-use Tempest\Router\Stateless;
-use Tempest\Router\Get;
-
-final readonly class JsonController
-{
-    #[Stateless]
-    #[Get('/json')]
-    public function json(string $path): Response
-    { /* … */ }
-}
-```
-
 ## Custom route attributes
 
 It is often a requirement to have a bunch of routes following the same specifications—for instance, using the same middleware, or the same URI prefix.

packages/router/src/Connect.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Connect implements Route
+final class Connect implements Route
 {
     public Method $method;
 

packages/router/src/Delete.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Delete implements Route
+final class Delete implements Route
 {
     public Method $method;
 

packages/router/src/GenericRouter.php

@@ -11,7 +11,6 @@
 use Tempest\Http\Request;
 use Tempest\Http\Response;
 use Tempest\Http\Responses\Ok;
-use Tempest\Http\Session\VerifyCsrfMiddleware;
 use Tempest\Router\Exceptions\ControllerActionHadNoReturn;
 use Tempest\Router\Exceptions\MatchedRouteCouldNotBeResolved;
 use Tempest\Router\Routing\Matching\RouteMatcher;
@@ -83,22 +82,6 @@ private function getCallable(): HttpMiddlewareCallable
                     )) {
                         return $callable($request);
                     }
-
-                    // Skip middleware that sets cookies or session values when the route is stateless
-                    if (
-                        $matchedRoute->route->handler->hasAttribute(Stateless::class)
-                        && in_array(
-                            needle: $middlewareClass->getName(),
-                            haystack: [
-                                VerifyCsrfMiddleware::class,
-                                SetCurrentUrlMiddleware::class,
-                                SetCookieMiddleware::class,
-                            ],
-                            strict: true,
-                        )
-                    ) {
-                        return $callable($request);
-                    }
                 }
 
                 /** @var HttpMiddleware $middleware */

packages/router/src/Get.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Get implements Route
+final class Get implements Route
 {
     public Method $method;
 

packages/router/src/Head.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Head implements Route
+final class Head implements Route
 {
     public Method $method;
 

packages/router/src/MatchedRoute.php

@@ -6,7 +6,7 @@
 
 use Tempest\Router\Routing\Construction\DiscoveredRoute;
 
-final readonly class MatchedRoute
+final class MatchedRoute
 {
     public function __construct(
         public DiscoveredRoute $route,

packages/router/src/Options.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Options implements Route
+final class Options implements Route
 {
     public Method $method;
 

packages/router/src/Patch.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Patch implements Route
+final class Patch implements Route
 {
     public Method $method;
 

packages/router/src/Post.php

@@ -8,7 +8,7 @@
 use Tempest\Http\Method;
 
 #[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
-final readonly class Post implements Route
+final class Post implements Route
 {
     public Method $method;