Merge branch '5.1'

* 5.1:
  Improved the HTTPCache examples mentioning s-maxage

Author: javiereguiluz

http_cache.rst

@@ -244,8 +244,9 @@ The *easiest* way to cache a response is by caching it for a specific amount of
         // somehow create a Response object, like by rendering a template
         $response = $this->render('blog/index.html.twig', []);
 
-        // cache for 3600 seconds
-        $response->setSharedMaxAge(3600);
+        // cache publicly for 3600 seconds
+        $response->setPublic();
+        $response->setMaxAge(3600);
 
         // (optional) set a custom Cache-Control directive
         $response->headers->addCacheControlDirective('must-revalidate', true);
@@ -257,7 +258,7 @@ Thanks to this new code, your HTTP response will have the following header:
 
 .. code-block:: text
 
-    Cache-Control: public, s-maxage=3600, must-revalidate
+    Cache-Control: public, maxage=3600, must-revalidate
 
 This tells your HTTP reverse proxy to cache this response for 3600 seconds. If *anyone*
 requests this URL again before 3600 seconds, your application *won't* be hit at all.

http_cache/esi.rst

@@ -105,14 +105,15 @@ independently of the rest of the page::
         public function about()
         {
             $response = $this->render('static/about.html.twig');
-            // sets the shared max age - which also marks the response as public
-            $response->setSharedMaxAge(600);
+            $response->setPublic();
+            $response->setMaxAge(600);
 
             return $response;
         }
     }
 
-In this example, the full-page cache has a lifetime of ten minutes.
+In this example, the response is marked as public to make the full page
+cacheable for all requests with a lifetime of ten minutes.
 Next, include the news ticker in the template by embedding an action.
 This is done via the ``render()`` helper (for more details, see how to
 :ref:`embed controllers in templates <templates-embed-controllers>`).
@@ -170,14 +171,19 @@ of the master page::
         public function latest($maxPerPage)
         {
             // ...
-            $response->setSharedMaxAge(60);
+            $response->setPublic();
+            $response->setMaxAge(60);
 
             return $response;
         }
     }
 
-With ESI, the full page cache will be valid for 600 seconds, but the news
-component cache will only last for 60 seconds.
+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
+response non-public and even non-cacheable, depending on your needs.
+
+Putting all the above code together, with ESI the full page cache will be valid
+for 600 seconds, but the news component cache will only last for 60 seconds.
 
 .. _http_cache-fragments:
 
@@ -233,14 +239,6 @@ possible.
     signed when using the fragment renderer and the ``render_esi`` Twig
     function.
 
-.. note::
-
-    Once you start using ESI, remember to always use the ``s-maxage``
-    directive instead of ``max-age``. As the browser only ever receives the
-    aggregated resource, it is not aware of the sub-components, and so it will
-    obey the ``max-age`` directive and cache the entire page. And you don't
-    want that.
-
 The ``render_esi`` helper supports two other useful options:
 
 ``alt``

http_cache/expiration.rst

@@ -26,14 +26,24 @@ 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->setSharedMaxAge(600);
+    $response->setPublic();
+    $response->setMaxAge(600);
 
 The ``Cache-Control`` header would take on the following format (it may have
 additional directives):
 
 .. code-block:: text
 
-    Cache-Control: public, s-maxage=600
+    Cache-Control: public, maxage=600
+
+.. note::
+
+    Using the ``setSharedMaxAge()`` method is not equivalent to using both
+    ``setPublic()`` and ``setMaxAge()`` methods. According to the
+    `Serving Stale Responses`_ section of RFC 7234, the ``s-maxage`` setting
+    (added by ``setSharedMaxAge()`` method) prohibits a cache to use a stale
+    response in ``stale-if-error`` scenarios. That's why it's recommended to use
+    both ``public`` and ``max-age`` directives.
 
 .. index::
     single: Cache; Expires header
@@ -76,9 +86,10 @@ servers should not send ``Expires`` dates more than one year in the future."
 
 .. note::
 
-    According to `RFC 7234 - Caching`_, the ``Expires`` header value is ignored
-    when the ``s-maxage`` or ``max-age`` directive of the ``Cache-Control``
-    header is defined.
+    According to the `Calculating Freshness Lifetime`_ section of RFC 7234,
+    the ``Expires`` header value is ignored when the ``s-maxage`` or ``max-age``
+    directive of the ``Cache-Control`` header is defined.
 
 .. _`expiration model`: https://tools.ietf.org/html/rfc2616#section-13.2
-.. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234#section-4.2.1
+.. _`Calculating Freshness Lifetime`: https://tools.ietf.org/html/rfc7234#section-4.2.1
+.. _`Serving Stale Responses`: https://tools.ietf.org/html/rfc7234#section-4.2.4