Add #[Template()] attribute

best_practices.rst

@@ -234,14 +234,6 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``@Template`` annotation is useful, but also involves some *magic*.
-Moreover, most of the time ``@Template`` is used without any parameters, which
-makes it more difficult to know which template is being rendered. It also hides
-the fact that a controller should always return a ``Response`` object.
-
 Use Dependency Injection to Get Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

components/http_kernel.rst

@@ -409,12 +409,12 @@ return a ``Response``.
 
 .. sidebar:: ``kernel.view`` in the Symfony Framework
 
-    There is no default listener inside the Symfony Framework for the ``kernel.view``
-    event. However, `SensioFrameworkExtraBundle`_ *does* add a listener to this
-    event. If your controller returns an array, and you place the `@Template`_
-    annotation above the controller, then this listener renders a template,
-    passes the array you returned from your controller to that template, and
-    creates a ``Response`` containing the returned content from that template.
+    There is a default listener inside the Symfony Framework for the ``kernel.view``
+    event. If your controller action returns an array, and you apply the
+    :ref:`#[Template()] attribute <templates-template-attribute>` to that
+    controller action, then this listener renders a template, passes the array
+    you returned from your controller to that template, and creates a ``Response``
+    containing the returned content from that template.
 
     Additionally, a popular community bundle `FOSRestBundle`_ implements
     a listener on this event which aims to give you a robust view layer
@@ -751,5 +751,4 @@ Learn more
 .. _`PHP FPM`: https://www.php.net/manual/en/install.fpm.php
 .. _`SensioFrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
 .. _variadic: https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list

templates.rst

@@ -470,6 +470,38 @@ If your controller does not extend from ``AbstractController``, you'll need to
 :ref:`fetch services in your controller <controller-accessing-services>` and
 use the ``render()`` method of the ``twig`` service.
 
+.. _templates-template-attribute:
+
+Another option is to use the ``#[Template()]`` attribute on the controller method
+to define the template to render::
+
+    // src/Controller/ProductController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
+
+    class ProductController extends AbstractController
+    {
+        #[Template('product/index.html.twig')]
+        public function index()
+        {
+            // ...
+
+            // when using the #[Template()] attribute, you only need to return
+            // an array with the parameters to pass to the template (the attribute
+            // is the one which will create and return the Response object).
+            return [
+                'category' => '...',
+                'promotions' => ['...', '...'],
+            ];
+        }
+    }
+
+.. versionadded:: 6.2
+
+    The ``#[Template()]`` attribute was introduced in Symfony 6.2.
+
 Rendering a Template in Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~