feature #45166 [HttpFoundation] add stale while revalidate cache header (remieuronews)

This PR was merged into the 6.1 branch.

Discussion
----------

[HttpFoundation] add stale while revalidate cache header

| Q             | A
| ------------- | ---
| Branch?       | 6.1
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Feat (symfony/symfony#45036)
| License       | MIT
| Doc PR       | [symfony/symfony-docs#... <!-- required for new features -->](symfony/symfony-docs#16445)

This PR allow support for RFC5861.
Meaning you can now use stale_while_revalidate and stale_if_error
https://httpwg.org/specs/rfc5861.html

Very interesting doc from Fastly on the subject:
https://developer.fastly.com/learning/concepts/stale/

Link to the issue
symfony/symfony#45036

Commits
-------

db553fb9f3 [cache] #45109 add stale while revalidate and stale if error cache header

Author: fabpot

CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+6.1
+---
+
+ * Add stale while revalidate and stale if error cache header
+
 6.0
 ---
 

Response.php

@@ -98,6 +98,8 @@ class Response
         'proxy_revalidate' => false,
         'max_age' => true,
         's_maxage' => true,
+        'stale_if_error' => true,         // RFC5861
+        'stale_while_revalidate' => true, // RFC5861
         'immutable' => false,
         'last_modified' => true,
         'etag' => true,
@@ -773,6 +775,38 @@ public function setMaxAge(int $value): static
         return $this;
     }
 
+    /**
+     * Sets the number of seconds after which the response should no longer be returned by shared caches when backend is down.
+     *
+     * This method sets the Cache-Control stale-if-error directive.
+     *
+     * @return $this
+     *
+     * @final
+     */
+    public function setStaleIfError(int $value): static
+    {
+        $this->headers->addCacheControlDirective('stale-if-error', $value);
+
+        return $this;
+    }
+
+    /**
+     * Sets the number of seconds after which the response should no longer return stale content by shared caches.
+     *
+     * This method sets the Cache-Control stale-while-revalidate directive.
+     *
+     * @return $this
+     *
+     * @final
+     */
+    public function setStaleWhileRevalidate(int $value): static
+    {
+        $this->headers->addCacheControlDirective('stale-while-revalidate', $value);
+
+        return $this;
+    }
+
     /**
      * Sets the number of seconds after which the response should no longer be considered fresh by shared caches.
      *
@@ -946,6 +980,14 @@ public function setCache(array $options): static
             $this->setSharedMaxAge($options['s_maxage']);
         }
 
+        if (isset($options['stale_while_revalidate'])) {
+            $this->setStaleWhileRevalidate($options['stale_while_revalidate']);
+        }
+
+        if (isset($options['stale_if_error'])) {
+            $this->setStaleIfError($options['stale_if_error']);
+        }
+
         foreach (self::HTTP_RESPONSE_CACHE_CONTROL_DIRECTIVES as $directive => $hasValue) {
             if (!$hasValue && isset($options[$directive])) {
                 if ($options[$directive]) {

Tests/ResponseTest.php

@@ -358,6 +358,44 @@ public function testSetSharedMaxAge()
         $this->assertEquals('public, s-maxage=20', $cacheControl);
     }
 
+    public function testSetStaleIfError()
+    {
+        $response = new Response();
+        $response->setSharedMaxAge(20);
+        $response->setStaleIfError(86400);
+
+        $cacheControl = $response->headers->get('Cache-Control');
+        $this->assertEquals('public, s-maxage=20, stale-if-error=86400', $cacheControl);
+    }
+
+    public function testSetStaleWhileRevalidate()
+    {
+        $response = new Response();
+        $response->setSharedMaxAge(20);
+        $response->setStaleWhileRevalidate(300);
+
+        $cacheControl = $response->headers->get('Cache-Control');
+        $this->assertEquals('public, s-maxage=20, stale-while-revalidate=300', $cacheControl);
+    }
+
+    public function testSetStaleIfErrorWithoutSharedMaxAge()
+    {
+        $response = new Response();
+        $response->setStaleIfError(86400);
+
+        $cacheControl = $response->headers->get('Cache-Control');
+        $this->assertEquals('stale-if-error=86400, private', $cacheControl);
+    }
+
+    public function testSetStaleWhileRevalidateWithoutSharedMaxAge()
+    {
+        $response = new Response();
+        $response->setStaleWhileRevalidate(300);
+
+        $cacheControl = $response->headers->get('Cache-Control');
+        $this->assertEquals('stale-while-revalidate=300, private', $cacheControl);
+    }
+
     public function testIsPrivate()
     {
         $response = new Response();