feature #14230 [Routing] Document the Route attribute (derrabus)

wouterj · wouterj · commit 7cfdbfcbea37 · 2020-10-11T22:34:33.000+02:00
This PR was squashed before being merged into the 5.x branch. Discussion ---------- [Routing] Document the Route attribute This PR documents the new `#[Route]` attribute that was introduced with symfony/symfony#37474 and thus closes #14188. For the routing configuration via Doctrine Annotations as well as PHP attributes, we use the very same class, `Symfony\Component\Routing\Annotation\Route`. This means that both mechanisms are equally powerful. Right now, there's nothing you can do with `@Route` that is impossible with `#[Route]` and vice versa. The main difference is that you don't need an external library for attributes because they're a native language feature. Because of that, I'd like to shift the general recommendation to use annotation towards attributes and recommend annotations as the fallback for projects that need to remain compatible with PHP 7. Right now, the `@Route` annotation is used throughout the documentation in two different ways: 1. Demonstrate how to use the annotation In this case, I've added an additional code block that shows the same configuration for attributes. I've consistently placed the attribute block before the annotation block. 2. Give context about the route configuration. When a code block illustrates the logic inside a controller action and the annotation is only used to provide context, I think it would create too much noise to show the attribute _and_ the annotation way. In `routing.rst`, I have replaced the annotation with an equal attribute in such cases. I think it would be a good idea to do the same with the rest of the documentation, but I'd like to discuss this with you before I change all those spots. Commits ------- 4ca794e [Routing] Document the Route attribute
diff --git a/_build/conf.py b/_build/conf.py
@@ -111,6 +111,7 @@
 lexers['markdown'] = TextLexer()
 lexers['php'] = PhpLexer(startinline=True)
 lexers['php-annotations'] = PhpLexer(startinline=True)
+lexers['php-attributes'] = PhpLexer(startinline=True)
 lexers['php-standalone'] = PhpLexer(startinline=True)
 lexers['php-symfony'] = PhpLexer(startinline=True)
 lexers['rst'] = RstLexer()
diff --git a/best_practices.rst b/best_practices.rst
@@ -223,12 +223,13 @@ important parts of your application.
 
 .. _best-practice-controller-annotations:
 
-Use Annotations to Configure Routing, Caching and Security
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Attributes or Annotations to Configure Routing, Caching and Security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using annotations for routing, caching and security simplifies configuration.
-You don't need to browse several files created with different formats (YAML, XML,
-PHP): all the configuration is just where you need it and it only uses one format.
+Using attributes or annotations for routing, caching and security simplifies
+configuration. You don't need to browse several files created with different
+formats (YAML, XML, PHP): all the configuration is just where you need it and
+it only uses one format.
 
 Don't Use Annotations to Configure the Controller Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
@@ -104,6 +104,7 @@ Markup Format        Use It to Display
 ``html+php``         PHP code blended with HTML
 ``ini``              INI
 ``php-annotations``  PHP Annotations
+``php-attributes``   PHP Attributes
 ===================  ======================================
 
 Adding Links
diff --git a/routing.rst b/routing.rst
