[RFC][Routing] Added the Route attribute

[derrabus]

Q	A
Branch?	5.2
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	N/A
License	MIT
Doc PR	symfony/symfony-docs#14230

I was wondering if we can make use of attributes as a replacement for Doctrine Annotations for configuring routes.

I have modified the existing AnnotationClassLoader so that it merges attributes and annotations. This way, an application could transparently switch from annotations to attributes. Moreover, the AnnotationClassLoader does not require an annotation reader anymore.

Since the chosen syntax #[…] is treated as a comment by php 7, I was able to use the existing annotation class, which makes the migration even easier.

Example with Doctrine Annotations

use Symfony\Component\Routing\Annotation\Route;

class ActionPathController
{
    /**
     * @Route("/path", name: "action")
     */
    public function action()
    {
    }
}

Same example with the proposed Attribute

use Symfony\Component\Routing\Annotation\Route;

class ActionPathController
{
    #[Route('/path', name: 'action')]
    public function action()
    {
    }
}

[ro0NL]

i like it :)

should we offer hybrid support by default? Thus vendor controllers could specify both attributes as well as annotations. Not sure this makes sense in practice though, otherwise i'd expect an exception if attributes and annotations are mixed&matched.
edit: nevermind, this works as expected already.

we could use sibling/nested attributes for rich options perhaps. Not sure it works out.

[derrabus]

Right now, you can mix&match attributes and annotations. It would have the same effect as if you specified multiple annotations. This was the easiest way to implement it, but this behavior is certainly debatable.

[ro0NL]

i think it's fair to assume both definitions remain equivalent. Then it works on all SF versions, loading either one or another.

I was wondering if we can make use of attributes as a replacement for Doctrine Annotations

raising the bigger question, is there any reason not to? Should we deprecate annotation support once we support php:^8?

[javiereguiluz]

Please note that the attribute syntax has just changed from << ... >> to @@... See https://wiki.php.net/rfc/shorter_attribute_syntax

[derrabus]

@javiereguiluz This has not been merged yet, has it?

[javiereguiluz]

Not merged yet ... but approved, so it will be merged "soon" (I was notified about this by this nice @beberlei service: https://php-rfc-watch.beberlei.de/)

[derrabus]

All right. If I changed the PR now, Travis won't be able to run my tests anymore. I don't expect the reflection API to be affected by the change, so all I will need to do is adjust the test fixtures and the attribute class itself to the new syntax. I'll do this as soon as Travis' nightly build supports it.

[derrabus]

Pending PR for the syntax change: php/php-src#5796

[derrabus]

I've pushed an update to this PR the other day.

• The PR is now incompatible with 8.0.0alpha1 and requires the changes of Attribute Amendments php/php-src#5751 to run.
  • PhpAttribute has been renamed to Attribute
  • The allowed targets of the Route attribute have been set to class and method (just like the annotation).
  • Now, we need to explicitly allow the attribute to be applied multiple times to the same structure, so I did just that.
• I've duplicated all test fixtures of AnnotationClassLoaderTest and rewrote the annotations to attributes. So we're running the same test suite for annotations and attributes now.

Some tests mocked Doctrine's annotation reader. I rewrote those test to use an actual annotation reader instead. It might be a good idea to backport that change, in order to ease the maintenance.

[derrabus]

I might need some help with getting Travis green: https://travis-ci.org/github/symfony/symfony/jobs/705695329

On the php 7.4 run, it looks like some piece of code is trying to parse my new attribute (which only works on php 8). Anything I can do to prevent that?

[nicolas-grekas]

patch .github/patch-types.php?

[derrabus]

patch .github/patch-types.php?

That did not help, apparently. 🙁

[moliata]

@javiereguiluz Just to chime in, @@ is still in "unknown status" given that it raises ambiguity in the PHP parser. Thus, whether the new syntax will be used depends on the namespaced names as tokens RFC.

[derrabus]

PHP attributes are basically a moving target at the moment. Just look at the changes between the alpha1 and alpha2 releases. And because I need a working testsuite, I won't anticipate any syntax changes until they actually hit the php 8 nightly build on travis.

Nevertheless, I think working with attributes at this early stage can be very helpful:

• We can find out if attributes are helpful and how we can make use of them in Symfony.
• We can give early feedback to the php dev team, which in turn might help them to fine-tune the feature before the final release.

Since Symfony 5.2 will stabilize together with php 8, I'm marking this PR as ready now. The current implementation of the PR works find with the alpha2 of php 8. If the PR gets merged, I'll monitor the php 8 build on Travis and adjust the implementation if necessary.

[fabpot]

Thank you @derrabus.

[TomasVotruba]

We've just added @Route attribute to @rectorphp:
rectorphp/rector#4350

Named parameters makes this very intuitive to migrate 👍

Note, there is no Symfony\Component\Routing\---->Attribute<----\Route class as in PR description.
The class is the same as before, ..\Annotation\Route.

[derrabus]

@TomasVotruba Thank you, I have updated the PR description. The first two iterations of the attribute syntax required me to introduce a dedicated attribute class, so this might have been a leftover from that time.

[TomasVotruba]

@derrabus Thanks 👍
I understand that, I rarely update the PR descriptions after design changes in them.

Next step: #38309