feat(router): add ability to skip middleware per route (#1472)

Author: innocenzi

docs/1-essentials/01-routing.md

@@ -374,7 +374,7 @@ Note that priority is defined using an integer. You can however use one of the b
 
 ### Middleware discovery
 
-Global middleware classes are discovered and sorted based on their priority. You can make a middleware class non-global by adding the `#[SkipDiscovery]` attribute:
+Global middleware classes are discovered and sorted based on their priority. You can make a middleware class non-global by adding the {b`#[Tempest\Discovery\SkipDiscovery]`} attribute:
 
 ```php
 use Tempest\Discovery\SkipDiscovery;
@@ -384,6 +384,48 @@ final readonly class ValidateWebhook implements HttpMiddleware
 { /* … */ }
 ```
 
+### Excluding route middleware
+
+Some routes may not require specific global middleware to be applied. For instance, API routes do not need CSRF protection. You may skip specific middleware by using the `without` argument of the route attribute.
+
+```php app/Slack/ReceiveInteractionController.php
+use Tempest\Router\Post;
+use Tempest\Http\Response;
+
+final readonly class ReceiveInteractionController
+{
+    #[Post('/slack/interaction', without: [VerifyCsrfMiddleware::class, SetCookieMiddleware::class])]
+    public function __invoke(): Response
+    {
+        // …
+    }
+}
+```
+
+### Group middleware
+
+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.
+
+```php Api.php
+#[Attribute(Attribute::IS_REPEATABLE | Attribute::TARGET_METHOD)]
+final readonly class Api implements Route
+{
+    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
+        ];
+    }
+}
+```
+
 ## Responses
 
 All requests to a controller action expect a response to be returned to the client. This is done by returning a `{php}View` or a `{php}Response` object.

packages/router/src/Connect.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::CONNECT;
     }

packages/router/src/Delete.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::DELETE;
     }

packages/router/src/GenericRouter.php

@@ -77,6 +77,15 @@ private function getCallable(): HttpMiddlewareCallable
 
         foreach ($middlewareStack->unwrap() as $middlewareClass) {
             $callable = new HttpMiddlewareCallable(function (Request $request) use ($middlewareClass, $callable) {
+                // We skip this middleware if it's ignored by the route
+                if ($this->container->has(MatchedRoute::class)) {
+                    $matchedRoute = $this->container->get(MatchedRoute::class);
+
+                    if (in_array($middlewareClass->getName(), $matchedRoute->route->without, strict: true)) {
+                        return $callable($request);
+                    }
+                }
+
                 /** @var HttpMiddleware $middleware */
                 $middleware = $this->container->get($middlewareClass->getName());
 

packages/router/src/Get.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::GET;
     }

packages/router/src/Head.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::HEAD;
     }

packages/router/src/Options.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::OPTIONS;
     }

packages/router/src/Patch.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::PATCH;
     }

packages/router/src/Post.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::POST;
     }

packages/router/src/Put.php

@@ -13,11 +13,13 @@
     public Method $method;
 
     /**
-     * @param class-string<HttpMiddleware>[] $middleware
+     * @param class-string<HttpMiddleware>[] $middleware Middleware specific to this route.
+     * @param class-string<HttpMiddleware>[] $without Middleware to remove from this route.
      */
     public function __construct(
         public string $uri,
         public array $middleware = [],
+        public array $without = [],
     ) {
         $this->method = Method::PUT;
     }