[RFC] Consistently use the word "attribute" in all symbols

[derrabus]

Description

Doctrine Annotations have served us well, but PHP attributes are the future.

Our strategy for Symfony 6 was to support Doctrine Annotations and PHP attributes as two ways of annotating pieces of configuration to code. In Symfony 7, attributes will be the only supported way. However, we still use the word "annotation" in the codebase in an abstract sense (PHP attributes are a form of annotation). This might be confusing, so we might consider using the work "attribute" everywhere consistently.

I've opened this issue to collect all occurrences of the term and to discuss the possible impact on downstream projects.

• The serializer integration of FrameworkBundle exposes a configuration option enable_annotations. Rename to enable_attributes.
• The validation integration of FrameworkBundle exposes a configuration option enable_annotations. Rename to enable_attributes.
• The Routing and Serializer components organize their attribute classes in a namespace called Annotation. Rename that namespace to Attribute.
• When loading routes from attributes, the loader type is annotation although attribute is already an alias for that. Make attribute the only possible type.
• Serializer uses a class named AnnotationLoader to load metadata from attributes. Rename to AttributeLoader.
• Validation uses a class named AnnotationLoader to load metadata from attributes. Rename to AttributeLoader.
• Routing contains classes AnnotationClassLoader and AnnotationDirectoryLoader for loading routes from attributes. Rename to AttributeClassLoader and AttributeDirectoryLoader.

If you find more TODOs, please drop a comment.

[nicolas-grekas]

I'm fine with all items except the second one:

The Routing and Serializer components organize their attribute classes in a namespace called Annotation. Rename that namespace to Attribute?

I think this can lead to costly migrations from 6 to 7. The benefit might not be worth the troubles.
If we really want to go this way, we could add the Attribute namespace and keep the Annotation one as an alias. But I wouldn't deprecate in the same version that introduces the alternative.

For validation, I'm also wondering if the move shouldn't do one more step and clean the way we create those objects. Right now, constructors are a bit strange. Maybe relying only on named args is possible?

[derrabus]

The Routing and Serializer components organize their attribute classes in a namespace called Annotation. Rename that namespace to Attribute?

I think this can lead to costly migrations from 6 to 7.

I don't know. In all of the codebases I've seen those attributes in action, they're imported like this:

use Symfony\Component\Routing\Annotation\Route;

This looks like a big search&replace to me. Your favorite IDE should be able to handle that.

[derrabus]

For validation, I'm also wondering if the move shouldn't do one more step and clean the way we create those objects.

I've created #51393 for that. This might be a bit heavier to migrate, I'm afraid.

[stof]

@derrabus a search-and-replace only works if you don't need to support multiple versions of Symfony in your code base.

[nicolas-grekas]

We should also consider if deprecating and providing the alternative in the same version isn't too harsh. We know this breaks migration paths for third party bundles. We could instead provide the alternative in 6.4, and deprecate in 7.1. We need to decide if this concern apply to the listed cases. WDYT?

[wouterj]

I'm not sure if there are many third party bundles that use attributes, given it needs to be enabled by the user for both validation and routing?

[alexandre-daubois]

• "The serializer integration of FrameworkBundle exposes a configuration option enable_annotations. Rename to enable_attributes" done by [FrameworkBundle][Validator] Deprecate annotation occurrences #51425
• "Serializer uses a class named AnnotationLoader to load metadata from attributes. Rename to AttributeLoader" is in progress on my side and will submit a PR soon [FrameworkBundle][Serializer] Deprecate annotations #51470
• "When loading routes from attributes, the loader type is annotation although attribute is already an alias for that. Make attribute the only possible type" is in progress on my side [FrameworkBundle][Routing] Deprecate annotations #51483
• "Routing contains classes AnnotationClassLoader and AnnotationDirectoryLoader for loading routes from attributes. Rename to AttributeClassLoader and AttributeDirectoryLoader" will come with the above item

[xabbuh]

I've checked three more boxes. The Attribute namespace is the only thing left to do, right?

[alexandre-daubois]

I'd say yes!

[nicolas-grekas]

Let's close this issue then? I don't mind the namespace - or I would mind the migration cost :)
We can always reconsider in 7.x (0 < x < 4).

[xabbuh]

I agree

[wouterj]

I think this is a good option: "We could instead provide the alternative in 6.4, and deprecate in 7.1."

Let's alias in 6.4/7.0 and start the deprecation path in 7.x. By the time 8.0 is released, libraries only need to support 6.4 and 7.x, meaning they can switch to the Attribute namespace. Applications can, whenever they want in the next 2 years, do a small find and replace dance.

Sure, the "Annotation" part doesn't mind an experienced PHP and Symfony developer that knows the time before PHP attributes. But it can already confuse people that are learning Symfony right now, and this will increase in significance the more we are away of the doctrine/annotations era.

[wouterj]

Here we go: #52294

[nicolas-grekas]

Thanks you all for the help!