minor #16998 [HttpKernel] Add #[Cache()] attribute (javiereguiluz)

This PR was merged into the 6.2 branch.

Discussion
----------

[HttpKernel] Add #[Cache()] attribute

Fixes #16974.

The only article I didn't update was `http_cache/validation.rst` because it uses lots of PHP logic to set cache headers, so I think it cannot be replicated with PHP attributes.

Commits
-------

1894141 Add #[Cache()] attribute

Author: javiereguiluz

http_cache.rst

@@ -191,24 +191,44 @@ Expiration Caching
 
 The *easiest* way to cache a response is by caching it for a specific amount of time::
 
-    // src/Controller/BlogController.php
-    use Symfony\Component\HttpFoundation\Response;
-    // ...
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        // src/Controller/BlogController.php
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
+
+        #[Cache(public: true, maxage: 3600, mustRevalidate: true)]
+        public function index()
+        {
+            return $this->render('blog/index.html.twig', []);
+        }
+
+    .. code-block:: php
 
-    public function index()
-    {
-        // somehow create a Response object, like by rendering a template
-        $response = $this->render('blog/index.html.twig', []);
+        // src/Controller/BlogController.php
+        use Symfony\Component\HttpFoundation\Response;
+        // ...
 
-        // cache publicly for 3600 seconds
-        $response->setPublic();
-        $response->setMaxAge(3600);
+        public function index()
+        {
+            // somehow create a Response object, like by rendering a template
+            $response = $this->render('blog/index.html.twig', []);
 
-        // (optional) set a custom Cache-Control directive
-        $response->headers->addCacheControlDirective('must-revalidate', true);
+            // cache publicly for 3600 seconds
+            $response->setPublic();
+            $response->setMaxAge(3600);
 
-        return $response;
-    }
+            // (optional) set a custom Cache-Control directive
+            $response->headers->addCacheControlDirective('must-revalidate', true);
+
+            return $response;
+        }
+
+.. versionadded:: 6.2
+
+    The ``#[Cache()]`` attribute was introduced in Symfony 6.2.
 
 Thanks to this new code, your HTTP response will have the following header:
 
@@ -316,6 +336,10 @@ Additionally, most cache-related HTTP headers can be set via the single
         'etag'             => 'abcdef'
     ]);
 
+.. tip::
+
+    All these options are also available when using the ``#[Cache()]`` attribute.
+
 Cache Invalidation
 ------------------
 

http_cache/cache_vary.rst

@@ -32,14 +32,28 @@ trigger a different representation of the requested resource:
     resource based on the URI and the value of the ``Accept-Encoding`` and
     ``User-Agent`` request header.
 
-The ``Response`` object offers a clean interface for managing the ``Vary``
-header::
+Set the ``Vary`` header via the ``Response`` object methods or the ``#[Cache()]``
+attribute::
 
-    // sets one vary header
-    $response->setVary('Accept-Encoding');
+.. configuration-block::
 
-    // sets multiple vary headers
-    $response->setVary(['Accept-Encoding', 'User-Agent']);
+    .. code-block:: php-attributes
 
-The ``setVary()`` method takes a header name or an array of header names for
-which the response varies.
+        // this attribute takes an array with the name of the header(s)
+        // names for which the response varies
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
+
+        #[Cache(vary: ['Accept-Encoding'])]
+        #[Cache(vary: ['Accept-Encoding', 'User-Agent'])]
+        public function index()
+        {
+            // ...
+        }
+
+    .. code-block:: php
+
+        // this method takes a header name or an array of header names for
+        // which the response varies
+        $response->setVary('Accept-Encoding');
+        $response->setVary(['Accept-Encoding', 'User-Agent']);

http_cache/esi.rst

@@ -166,20 +166,41 @@ used ``render()``.
 The embedded action can now specify its own caching rules entirely independently
 of the main page::
 
-    // src/Controller/NewsController.php
-    namespace App\Controller;
+.. configuration-block::
 
-    // ...
-    class NewsController extends AbstractController
-    {
-        public function latest($maxPerPage)
+    .. code-block:: php-attributes
+
+        // src/Controller/NewsController.php
+        namespace App\Controller;
+
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
+
+        class NewsController extends AbstractController
         {
-            // sets to public and adds some expiration
-            $response->setSharedMaxAge(60);
+            #[Cache(smaxage: 60)]
+            public function latest($maxPerPage)
+            {
+                // ...
+            }
+        }
 
-            return $response;
+    .. code-block:: php
+
+        // src/Controller/NewsController.php
+        namespace App\Controller;
+
+        // ...
+        class NewsController extends AbstractController
+        {
+            public function latest($maxPerPage)
+            {
+                // sets to public and adds some expiration
+                $response->setSharedMaxAge(60);
+
+                return $response;
+            }
         }
-    }
 
 In this example, the embedded action is cached publicly too because the contents
 are the same for all requests. However, in other cases you may need to make this

http_cache/expiration.rst

@@ -24,10 +24,25 @@ Expiration with the ``Cache-Control`` Header
 Most of the time, you will use the ``Cache-Control`` header, which
 is used to specify many different cache directives::
 
-    // sets the number of seconds after which the response
-    // should no longer be considered fresh by shared caches
-    $response->setPublic();
-    $response->setMaxAge(600);
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
+
+        #[Cache(public: true, maxage: 600)]
+        public function index()
+        {
+            // ...
+        }
+
+    .. code-block:: php
+
+        // sets the number of seconds after which the response
+        // should no longer be considered fresh by shared caches
+        $response->setPublic();
+        $response->setMaxAge(600);
 
 The ``Cache-Control`` header would take on the following format (it may have
 additional directives):
@@ -57,13 +72,28 @@ or disadvantage to either.
 
 According to the HTTP specification, "the ``Expires`` header field gives
 the date/time after which the response is considered stale." The ``Expires``
-header can be set with the ``setExpires()`` ``Response`` method. It takes a
-``DateTime`` instance as an argument::
+header can be set with the ``expires`` option of the ``#[Cache()]`` attribute or
+the ``setExpires()`` ``Response`` method::
+
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
+
+        #[Cache(expires: '+600 seconds')]
+        public function index()
+        {
+            // ...
+        }
+
+    .. code-block:: php
 
-    $date = new DateTime();
-    $date->modify('+600 seconds');
+        $date = new DateTime();
+        $date->modify('+600 seconds');
 
-    $response->setExpires($date);
+        $response->setExpires($date);
 
 The resulting HTTP header will look like this:
 
@@ -73,8 +103,8 @@ The resulting HTTP header will look like this:
 
 .. note::
 
-    The ``setExpires()`` method automatically converts the date to the GMT
-    timezone as required by the specification.
+    The ``expires` option and the ``setExpires()`` method automatically convert
+    the date to the GMT timezone as required by the specification.
 
 Note that in HTTP versions before 1.1 the origin server wasn't required to
 send the ``Date`` header. Consequently, the cache (e.g. the browser) might

http_cache/ssi.rst

@@ -88,28 +88,55 @@ Suppose you have a page with private content like a Profile page and you want
 to cache a static GDPR content block. With SSI, you can add some expiration
 on this block and keep the page private::
 
-    // src/Controller/ProfileController.php
-    namespace App\Controller;
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        // src/Controller/ProfileController.php
+        namespace App\Controller;
+
+        use Symfony\Component\HttpKernel\Attribute\Cache;
+        // ...
 
-    // ...
-    class ProfileController extends AbstractController
-    {
-        public function index(): Response
+        class ProfileController extends AbstractController
         {
-            // by default, responses are private
-            return $this->render('profile/index.html.twig');
+            public function index(): Response
+            {
+                // by default, responses are private
+                return $this->render('profile/index.html.twig');
+            }
+
+            #[Cache(smaxage: 600)]
+            public function gdpr(): Response
+            {
+                return $this->render('profile/gdpr.html.twig');
+            }
         }
 
-        public function gdpr(): Response
+    .. code-block:: php
+
+        // src/Controller/ProfileController.php
+        namespace App\Controller;
+
+        // ...
+        class ProfileController extends AbstractController
         {
-            $response = $this->render('profile/gdpr.html.twig');
+            public function index(): Response
+            {
+                // by default, responses are private
+                return $this->render('profile/index.html.twig');
+            }
+
+            public function gdpr(): Response
+            {
+                $response = $this->render('profile/gdpr.html.twig');
 
-            // sets to public and adds some expiration
-            $response->setSharedMaxAge(600);
+                // sets to public and adds some expiration
+                $response->setSharedMaxAge(600);
 
-            return $response;
+                return $response;
+            }
         }
-    }
 
 The profile index page has not public caching, but the GDPR block has
 10 minutes of expiration. Let's include this block into the main one: