Symfony 6 Certification New exam with updated questions 100% online Show your expertise

New in Symfony 5.1: Route annotations priority

Warning: This post is about an unsupported Symfony version. Some of this information may be out of date. Read the most recent Symfony Docs.

Contributed by
Nicolas Grekas
in #35608.

Symfony routes can include variable parts called parameters to match different URLs sharing the same structure. Although you can restrict the values of each route parameters, two or more routes can match the same URL.

In those cases Symfony uses the route that was defined first. If you define the routes using YAML, XML or PHP files, you can reorder the routes to fit your needs. However, when using annotations to define routes, reordering can be much harder.

That's why in Symfony 5.1 we've added a route priority option, but only for annotations. As usual in other parts of Symfony, priority is a positive or negative integer which defaults to 0. The higher its value, the more priority the route has:

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class MyController extends AbstractController
     * @Route("/{some_parameter}", name="route1")
    public function someMethod(): Response
        // ...

     * @Route("/foo", priority=10, name="route2")
    public function anotherMethod(): Response
        // ...

In Symfony 5.1, when receiving a request for the /foo URL, Symfony will match the route2 because its priority is 10 (and the route1 priority is the default 0).

Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.


Nice feature ! Always had to explain my students that in this case they had to put methods in the right order or create a requirements which would excluse "foo" from their first route :D
Nice!, thank you Nicolas Grekas.
Nice feature! 🎉
Good job
Nice feature ;)
This was needed since route annotations were introduced. Thank you very much!
I always used both requirements and logical order, this comes in handy!
A very useful addition, thanks!
Good job Nicolas :)
Woohoo!! That's an awesome feature, I waited for it so long time!!!
Great news! Thanks guys!
Nice! Can we put negative priorities on some routes ?
In 2016, the discussion was clear : "The kind of conflicts mentioned in this issue mostly happen in the context of one file, so reorganizing one file is easy." fabpot

So I used the annotation "requirements" which I think is clearer than the "priority". When you or somebody else read your code you can see that the matching won't operate. Because it's in the regexp, not just a number. Priority might be easyer to write.

But it is still a good to know that thing can change!
@Guillaume yes, you can use negative priorities. It's mentioned in the blog post :)

@Christophe you are right. It feels better to add restrictions to routes to control the URL matching. However, sometimes (e.g. with catch-all routes) a priority is a much better solution (e.g. give the catch-all route a big negative priority and most of your problems will be solved).
Finally ! This is a very good news ! Thank you !
nice job
Can't wait for 5.1 to be out!
Thanks it's amazing!

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.