wip

Author: brendt

composer.lock

@@ -57,6 +57,10 @@ The second reason this argument fails is that in real project, route files becom
 
 ## Route Grouping
 
+:::info
+Since writing this blog post, route grouping in Tempest has gotten a serious update. Read all about it [here](/blog/route-decorators)
+:::
+
 The second-biggest argument against route attributes is the "route grouping" argument. A single route configuration file like for example in Laravel, allows you to reuse route configuration by grouping them together:
 
 ```php
@@ -73,56 +77,30 @@ Route::middleware([AdminMiddleware::class])
 
 Laravel's approach is really useful because you can configure several routes as a single group, so that you don't have to repeat middleware configuration, prefixes, etc. for _every individual route_. With route attributes, you cannot do that — or can you?
 
-Tempest's route attributes are designed so that you can make your own. Even better: you're encouraged to do so! Let's say we have a route group specifically for admins: they need to be prefixed, and they need an extra middleware for checking authentication. Here's what that looks like in Tempest. First you make a `AdminRoute` class representing the route group:
+Tempest has a concept called [route decorators](/2.x/essentials/routing#route-decorators-route-groups) which are a super convenient way to model route groups and share behavior. They look like this:
 
 ```php
-use Attribute;
-use Tempest\Http\Method;
-use Tempest\Router\Route;
-use function Tempest\Support\path;
-
-#[Attribute]
-final class AdminRoute implements Route
-{
-    public function __construct(
-        public string $uri,
-        public array $middleware = [],
-        public Method $method = Method::GET,
-    ) {
-        $this->uri = path('/admin', $uri);
-        $this->middleware = [AdminMiddleware::class, ...$middleware];
-    }
-}
-```
-
-And then you simply use that attribute for admin routes:
-
-```php
-use Tempest\Http\Method;
-use Tempest\Http\Response;
-
+#[{:hl-type:Admin:}, {:hl-type:Books:}]
 final class BookAdminController
 {
-    #[AdminRoute('/books')]
-    public function index(): Response { /* … */ }
+    #[Get('/books')]
+    public function index(): View { /* … */ }
 
-    #[AdminRoute('/books/{book}/show')]
-    public function show(Book $book): Response { /* … */ }
+    #[Get('/books/{book}/show')]
+    public function show(Book $book): View { /* … */ }
 
-    #[AdminRoute('/books/new', method: Method::POST)]
-    public function new(StoreBookRequest $request): Response { /* … */ }
+    #[Post('/books/new')]
+    public function new(): View { /* … */ }
 
-    #[AdminRoute('/books/{book}/update', method: Method::POST)]
-    public function update(BookRequest $bookRequest, Book $book): Response { /* … */ }
+    #[Post('/books/{book}/update')]
+    public function update(): View { /* … */ }
 
-    #[AdminRoute('/books/{book}/delete', method: Method::DELETE)]
-    public function delete(Book $book): Response { /* … */ }
+    #[Delete('/books/{book}/delete')]
+    public function delete(): View { /* … */ }
 }
 ```
 
-Of course, you could make variations like `AdminGet`, `AdminPost`, and `AdminDelete` as well, whatever fits your case. You could even make a `BookRoute` specifically for books.
-
-So, the second argument against route attributes also falls short: you can in fact create route groups. I'd even say I prefer modelling route groups as classes instead of relying on configuration. That might be preference, of course, but I definitely don't feel like one approach is better than the other; which means the second argument fails as well.
+You can read more about its design in [this blog post](/blog/route-decorators).
 
 ## Route Collisions
 

src/Web/Blog/articles/2025-03-30-about-route-attributes.md

@@ -5,7 +5,7 @@ author: brent
 tag: release
 ---
 
-When I began working on Tempest, the very first things I added were a container and a router. I already had a clear vision on what I wanted routing to look like: to embrace attributes to keep routes and controller actions close together. Coming from Laravel, this is quite a different approach, and so I wrote about [my vision on the router's design](/blog/about-route-attributes) to make sure everyone understood.
+When I began working on Tempest, the very first features were a container and a router. I already had a clear vision on what I wanted routing to look like: to embrace attributes to keep routes and controller actions close together. Coming from Laravel, this is quite a different approach, and so I wrote about [my vision on the router's design](/blog/about-route-attributes) to make sure everyone understood.
 
 > If you decide that route attributes aren't your thing then, well, Tempest won't be your thing. That's ok. I do hope that I was able to present a couple of good arguments in favor of route attributes; and that they might have challenged your opinion if you were absolutely against them.
 
@@ -65,12 +65,12 @@ final class BookAdminController
 }
 ```
 
-While I really like attribute-based routing, grouping route bevaiour does feel… suboptimal with this approach. A couple of nitpicks:
+While I really like attribute-based routing, grouping route behavior does feel… suboptimal because of attributes. A couple of nitpicks:
 
-- Tempest's default route attributes are represented by HTTP verbs: `#[Get]`, `#[Post]`, etc. Making admin variants for each verb might be tedious, so in my previous example I decided to use one `#[AdminRoute]`, where the verb would be specified manually. There's nothing stopping me from adding `#[AdminGet]`, `#[AdminPost]`, etc; but it doesn't feel super clean either.
-- When you prefer to namespace admin-specific route attributes like `#[Admin\Get]`, and `#[Admin\Post]`, you end up with naming collisions between normal- and admin versions. I've always found those types of ambiguities to increase cognitive load while coding.
-- This approach doesn't really scale: say there are two types of route groups that require a specific middleware (`AuthMiddleware`, for example), then you end up making two or more route attributes, duplicating adding the `AuthMiddleware` to both.
-- Say you want nested route groups: one for admin routes and then one for book routes (with a `/admin/books` prefix), you end up with yet another `#[AdminBookRoute]` attribute, not ideal. 
+- Tempest's default route attributes are represented by HTTP verbs: `#[Get]`, `#[Post]`, etc. Making admin variants for each verb might be tedious, so in my previous example I decided to use one `#[AdminRoute]`, where the verb would be specified manually. There's nothing stopping me from adding `#[AdminGet]`, `#[AdminPost]`, etc; but it doesn't feel super clean.
+- When you prefer to namespace admin-specific route attributes like `#[Admin\Get]`, and `#[Admin\Post]`, you end up with naming collisions between normal- and admin versions. I've always found those types of ambiguities to increase cognitive load while coding.
+- This approach doesn't really scale: say there are two types of route groups that require a specific middleware (`AuthMiddleware`, for example), then you end up making two or more route attributes, duplicating that logic of adding `AuthMiddleware` to both.
+- Say you want nested route groups: one for admin routes and then one for book routes (with a `/admin/books` prefix), you end up with yet another variant called `#[AdminBookRoute]` attribute, not ideal. 
 
 So… what's the solution? I first looked at Symfony, which also uses attributes for routing:
 
@@ -95,10 +95,136 @@ class BookAdminController extends AbstractController
 }
 ```
 
-I think Symfony's approach gets us halfway there: it has the benefit of being able to define "shared route behavior" on the controller level, but not across controllers. You could create abstract controllers like `AdminController` and `AdminBookController`, but I find that a very cumbersome approach. It also doesn't scale when you want to combine multiple route behaviors horizontally because PHP doesn't have multi-inheritance. On top of that, I also like Tempest's design of using HTTP verbs to model route attributes like `#[Get]` and `#[Post]`, which is missing with Symfony. All of that to say, I like Symfony's approach, but I feel like there's even more room for improvement.
+I think Symfony's approach gets us halfway there: it has the benefit of being able to define "shared route behavior" on the controller level, but not across controllers. You could create abstract controllers like `AdminController` and `AdminBookController`, which doesn't scale horizontally when you want to combine  multiple route groups, because PHP doesn't have multi-inheritance. On top of that, I also like Tempest's design of using HTTP verbs to model route attributes like `#[Get]` and `#[Post]`, which is missing with Symfony. All of that to say, I like Symfony's approach, but I feel like there's room for improvement.
 
 With the scene now being set, let's see the design we ended up with in Tempest.
 
 ## A Tempesty solution
 
-A week ago, my production server suddenly died. After some debugging, I realized the problem had to do with my recent refactor from [my blog](https://stitcher.io) to Tempest. The RSS- and meta-image routes apparently started a session (which were stored as files), which eventually led to the server being overflooded with unused files after two weeks. I had forgotten to exclude these routes from the default web flow. 
+A week ago, my production server suddenly died. After some debugging, I realized the problem had to do with the recent refactor of [my blog](https://stitcher.io) to Tempest. The RSS and meta-image routes apparently started a session, which eventually led to the server being overflooded with hundreds of RSS reader- and social media requests per minute, each of them starting a new session. The solution was to remove all session-related middleware (CSRF protection, and "back URL" support) from these routes. While trying to come up with a proper solution, I had a realization: instead of making a "stateless route" class, why not add an attribute that worked _alongside_ the existing route attributes? That's what led to a new `#[Stateless]` attribute:
+
+```php
+#[Stateless, {:hl-type:Get:}('/rss')]
+public function rss(): Response {}
+```
+
+This felt like a really nice solution: I didn't have to make my own route attributes anymore, but could instead "decorate" them with additional functionality. The first iteration of the `#[Stateless]` attribute was rather hard-coded in Tempest's router (I was on the clock, trying to revive my server), it looked something like this:
+
+```php
+// 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);
+}
+```
+
+I knew, however, that it would be trivial to make this into a reusable pattern. A couple of days later and that's exactly what I did: route decorators are Tempest's new way of modeling grouped route behavior, and I absolutely love them. Here's a quick overview.
+
+First, route decorators work _alongside_ route attributes, not as a _replacement_. This means that they can be combined in any way you'd like, and they should all work together seeminglessly:
+
+```php
+final class BookAdminController
+{
+    #[{:hl-type:Admin:}, {:hl-type:Books:}, {:hl-type:Get:}('/{book}/show')]
+    public function show(Book $book): View { /* … */ }
+    
+    // …
+}
+```
+
+Furthermore, route decorators can also be defined on the controller level, which means they'll be applied to all its actions:
+
+```php
+#[{:hl-type:Admin:}, {:hl-type:Books:}]
+final class BookAdminController
+{
+    #[Get('/books')]
+    public function index(): View { /* … */ }
+    
+    #[Get('/books/{book}/show')]
+    public function show(Book $book): View { /* … */ }
+    
+    #[Post('/books/new')]
+    public function new(): View { /* … */ }
+    
+    #[Post('/books/{book}/update')]
+    public function update(): View { /* … */ }
+    
+    #[Delete('/books/{book}/delete')]
+    public function delete(): View { /* … */ }
+}
+```
+
+Finally, you're encouraged to make your custom route attributes as well (you might have already guessed that because of `#[Admin]` and `#[Books]`). Here's what both of these attributes would look like:
+
+```php
+use Attribute;
+use Tempest\Router\RouteDecorator;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
+final readonly class Admin implements RouteDecorator
+{
+    public function decorate(Route $route): Route
+    {
+        $route->uri = path('/admin', $route->uri)->toString();
+        $route->middleare[] = AdminMiddleware::class;
+
+        return $route;
+    }
+}
+```
+
+```php
+use Attribute;
+use Tempest\Router\RouteDecorator;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
+final readonly class Books implements RouteDecorator
+{
+    public function decorate(Route $route): Route
+    {
+        $route->uri = path('/books', $route->uri)->toString();
+
+        return $route;
+    }
+}
+```
+
+You can probably guess what a route decorator's job is: it is passed the current route, it can do some changes to it, and then return it. You can add and combine as many route decorators as you'd like, and Tempest's router will stitch them all together. Under the hood, that looks like this:
+
+```php
+// Get the route attribute
+$route = $method->getAttributes(Route::class);
+            
+// Get all decorators from the method and its controller class
+ $decorators = [
+    ...$method->getDeclaringClass()->getAttributes(RouteDecorator::class),
+    ...$method->getAttributes(RouteDecorator::class),
+];
+
+// Loop over each decorator and apply it one by one
+foreach ($decorators as $decorator) {
+    $route = $decorator->decorate($route);
+}
+```
+
+As an added benefit: all of this route decorating is done during [Tempest's discovery phase](/2.x/internals/discovery), which means the decorated route will be cached, and decorators themselves won't be run in production.
+
+On top of adding the {b`Tempest\Router\RouteDecorator`} interface, I've also added a couple of built-in route decorators that come with the framework:
+
+- {b`Tempest\Router\Prefix`}: which adds a prefix to all decorated routes.
+- {b`Tempest\Router\WithMiddleware`}: which adds one or more middleware classes to all decorated routes.
+- {b`Tempest\Router\WithoutMiddleware`}: which explicitely removes one or more middleware classes from the default middleware stack to all decorated routes.
+- {b`Tempest\Router\Stateless`}: which will remove all session and cookie related middleware from the decorated routes.
+
+I really like the solution we ended up with. I think it combines the best of both worlds. Maybe you have some thoughts about it as well? [Join the Tempest Discord](/discord) to let us know! You can also read all the details of route decorators [in the docs](/2.x/essentials/routing#route-decorators-route-groups).

src/Web/Blog/articles/2025-11-10-route-decorators.md

@@ -64,6 +64,7 @@
 .hl-property > .hl-keyword {
 	color: var(--code-property);
 }
+.hl-type > span,
 .hl-type {
 	color: var(--code-type);
 }