[Router]Add middleware to annotation router

[xuey490]

Description

I developed my own framework based on the Symfony framework for the underlying code. It is basically fully compatible with Symfony code, and I have implemented middleware for controller routing. Here's a demo code example: I hope the official team will also add such a feature.

This is my framework project，https://github.com/xuey490/novaphp

<?php
namespace App\Controllers;

use Framework\Attributes\Route;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

#[Route(prefix: '/api/v1', middleware: [\App\Middleware\AuthMiddleware::class , \App\Middleware\LogMiddleware::class ])]
class DemoController
{
    #[Route(path: '/users', methods: ['GET'], name: 'user.list' , middleware: [\App\Middleware\AuthMiddleware::class] )]
    public function list() { 
		echo 'list';
	}
}

Example

<?php
namespace App\Controllers;

use Framework\Attributes\Route;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;


#[Route(prefix: '/api/v1', middleware: [\App\Middleware\AuthMiddleware::class , \App\Middleware\LogMiddleware::class ])]
class DemoController
{
    #[Route(path: '/users', methods: ['GET'], name: 'user.list' , middleware: [\App\Middleware\AuthMiddleware::class] )]
    public function list() { 
		echo 'list';
	}
}

[xuey490]

Initially, I implemented annotation routing using doctrine/annotations. Later, I learned that the official team no longer supports doctrine/annotations. Therefore, I reconsidered using Symfony's native annotation routing, but encountered difficulties integrating middleware with it. Although I eventually managed to load middleware on annotation routing, I still hope that the Symfony official team can consider adding a parameter like _middleware to the default parameters of annotation routing.

[derrabus]

Can you elabote a bit more on how your middleware classes work and how this feature fits into Symfony's existing event-based architecture?

[xuey490]

1.Typical execution flow of middleware:

In My this proposal, middleware classes follow the PSR-15 MiddlewareInterface pattern and are designed to participate in the HTTP request-response lifecycle in a linear, composable pipeline. Each middleware can:

• Inspect or modify the incoming Request
• Short-circuit the flow by returning a Response early (e.g., authentication failure)
• Delegate to the next callable in the chain via a RequestHandlerInterface
• The key innovation is the ability to declare middleware directly on routes using PHP attributes, for example:

interface MiddlewareInterface
{
    public function process(Request $request, RequestHandlerInterface $handler): Response;
}

class AuthMiddleware implements MiddlewareInterface
{
    public function process(Request $request, RequestHandlerInterface $handler): Response
    {
        if (!$this->hasValidToken($request)) {
            return new JsonResponse(['error' => 'Unauthorized'], 401);
        }

        return $handler->handle($request); // 继续执行下一个
    }
}

This makes middleware usage explicit, route-scoped, and easy to reason about — developers can immediately see which layers of logic apply to a given endpoint.

This pattern is highly clear, composable, and easy to test. It is also widely used in frameworks such as Laravel, Slim, and Express.js.

2.How does this fit into Symfony’s event system?

Symfony’s EventDispatcher is powerful and flexible, with events like kernel.request, kernel.view, and kernel.response. However, there are important differences:

Aspect	Event System	Middleware (Proposed)
Execution Model	Broadcast: many listeners react independently	Chain: ordered, sequential, short-circuitable
Scope	Global or conditionally applied	Can be attached per-route or per-controller
Intent Clarity	Implicit: behavior spread across services	Explicit: declared directly where used
Control Flow	Listeners cannot naturally "stop" the chain	Middleware can return a response and halt processing

For example:

• You want to add JWT authentication to the /api/* route.Using the Event System: You need to register an onKernelRequest listener, determine if the path starts with /api/, and then perform authentication. This leads to scattered logic and poor maintainability.
• Using Middleware: Directly declare middleware:[JwtAuthMiddleware::class] in the route attribute. This ensures clear responsibilities and easy reusability.

Therefore, middleware is not a replacement for events. Instead, it is a higher-level abstraction used to clearly express the intent of the "request processing chain".

3.How to integrate with Symfony's existing architecture?

Symfony already supports HTTP middleware, but it requires manual configuration, which is not flexible enough.
Since Symfony 4.3, Symfony has provided middleware support for Kernel::handle() (via HttpKernelInterface).

✅ 3.1Symfony Middleware : Manually build the middleware pipeline in the front controller

// public/index.php
$middlewareStack = [
    new CorsMiddleware(),
    new JsonRequestMiddleware(),
    new AuthenticationMiddleware(),
];

$handler = new ControllerRequestHandler($kernel);
foreach (array_reverse($middlewareStack) as $middleware) {
    $handler = new MiddlewareRequestHandler($middleware, $handler);
}

$response = $handler->handle($request);

✅ 3.2 Automatically inject middleware via route metadata (this is exactly the feature I propose!)

// 在某个事件监听器中
public function onKernelRequest(RequestEvent $event)
{
    $request = $event->getRequest();
    $routeName = $request->attributes->get('_route');

    $middlewareClasses = $this->routeMiddlewareResolver->getMiddlewaresForRoute($routeName);

    $pipeline = new MiddlewarePipeline();
    foreach ($middlewareClasses as $middlewareClass) {
        $pipeline->pipe($this->container->get($middlewareClass));
    }

    $response = $pipeline->process($request, $this->finalHandler);

    if ($response) {
        $event->setResponse($response);
    }
}

The proposed feature—declaring middleware on routes through attribute annotations—fills a gap in Symfony.
Ideal implementation approach:

• Read the middleware attribute in AnnotationClassLoader or AttributeRouteLoader.
• Attach middleware information to the default values of the Route object (e.g., defaults['middleware']).
• Dynamically construct and execute the middleware pipeline based on the current route in a custom MiddlewareListener or RequestEvent listener.
• This enables "declarative middleware" while being fully compatible with the existing event system.

This enables "declarative middleware" while being fully compatible with the existing event system.

4. Why is this feature worth adding to Symfony Core?

1. Modern development experience: Frameworks like Laravel, Express, and FastAPI all support similar syntax, and developers expect this intuitive approach.
2. Improved readability and maintainability: It is easy to see at a glance which middleware is used by whom.
3. Better separation of concerns: Separate cross-cutting concerns (such as authentication and logging) from controllers.
4. Progressive adoption: It does not affect the existing event system and only provides a higher-level abstraction.

In short: middleware complements the event system, rather than replacing it. Events remain ideal for cross-cutting concerns (e.g., logging, metrics), while middleware excels at request preprocessing with clear ownership and ordering.

[xuey490]

I apologize for my poor English. I organized my words with the help of AI LLM, and I hope you can understand.

[tsantos84]

I like this approach. The more we use annotations more the code gets readable and maintainable.
I proposed similar to this here and the final thoughts is that we can expand the concept to any service.

[xuey490]

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

#[annotate('true'),group(['prefix' => '/home','middleware'=>'auth'])]
class MyController extends Controller
{
    #[get('/show')]
    public function show()
    {
        echo 'show';
    }
	
    #[get('/show2')]
    public function show2()
    {
        echo 'show2';
    }	
}

laravel had annotations router inject middleware function . https://laravel.com/docs/12.x/middleware

[derrabus]

General note: It's fine if you use an LLM for translation purposes, if that makes it easier to communicate with us. However, it's a different story if you let the LLM lead the debate. I need to understand your motivation, your reasoning behind the feature you're proposing. The lengthy text above reads as if you've instructed ChatGPT to answer my questions and to find arguments in favor of the solution you're proposing.

Back to topic: My problem is that the Symfony event architecture is that it is somewhat orthogonal to a middleware system. All the use-cases you've listed for middleware, such as authentication and logging, are currently implemented through events. Since you've mentioned Slim as an example: Slim uses middleware for those concerns instead of events and that also works pretty well for them.

Both architectures work fine on their own, but I'm afraid it might get complicated if you mix them both. This is why I've asked about how you intend to integrate your middleware system into the existing event architecture.