Improved the HTTPCache examples mentioning s-maxage

http_cache.rst

@@ -249,8 +249,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);
@@ -262,7 +263,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,22 @@ 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()`` may seem equivalent to using both ``setPublic()``
+    and ``setMaxAge()`` methods. However, their behavior is different in a
+    ``stale-if-error`` scenario and that's why it's recommended to use both
+    ``public`` and ``max-age`` directives.
 
 .. index::
     single: Cache; Expires header