From 30f32d4673c5657e1ba4c06d4b074b0360416451 Mon Sep 17 00:00:00 2001
From: Oleksandr Savchenko <savchenko.oleksandr.ua@gmail.com>
Date: Mon, 6 Apr 2020 15:14:17 +0300
Subject: [PATCH] Document all core response http control directives

---
 components/http_foundation.rst                | 19 +++++++++-----
 .../http_kernel_httpkernelinterface.rst       | 26 ++++++++++++-------
 http_cache.rst                                | 18 ++++++++-----
 3 files changed, 40 insertions(+), 23 deletions(-)

diff --git a/components/http_foundation.rst b/components/http_foundation.rst
index 678db631be8..7b7886ec60a 100644
--- a/components/http_foundation.rst
+++ b/components/http_foundation.rst
@@ -489,13 +489,18 @@ can be used to set the most commonly used cache information in one method
 call::
 
     $response->setCache([
-        'etag'          => 'abcdef',
-        'last_modified' => new \DateTime(),
-        'max_age'       => 600,
-        's_maxage'      => 600,
-        'private'       => false,
-        'public'        => true,
-        'immutable'     => true,
+        'must_revalidate'  => false,
+        'no_cache'         => false,
+        'no_store'         => false,
+        'no_transform'     => false,
+        'public'           => true,
+        'private'          => false,
+        'proxy_revalidate' => false,
+        'max_age'          => 600,
+        's_maxage'         => 600,
+        'immutable'        => true,
+        'last_modified'    => new \DateTime(),
+        'etag'             => 'abcdef'
     ]);
 
 To check if the Response validators (``ETag``, ``Last-Modified``) match a
diff --git a/create_framework/http_kernel_httpkernelinterface.rst b/create_framework/http_kernel_httpkernelinterface.rst
index 9207ba342b0..350993e3d7d 100644
--- a/create_framework/http_kernel_httpkernelinterface.rst
+++ b/create_framework/http_kernel_httpkernelinterface.rst
@@ -117,22 +117,28 @@ The Response class contains methods that let you configure the HTTP cache. One
 of the most powerful is ``setCache()`` as it abstracts the most frequently used
 caching strategies into a single array::
 
-    $date = date_create_from_format('Y-m-d H:i:s', '2005-10-15 10:00:00');
-
     $response->setCache([
-        'public'        => true,
-        'etag'          => 'abcde',
-        'last_modified' => $date,
-        'max_age'       => 10,
-        's_maxage'      => 10,
+        'must_revalidate'  => false,
+        'no_cache'         => false,
+        'no_store'         => false,
+        'no_transform'     => false,
+        'public'           => true,
+        'private'          => false,
+        'proxy_revalidate' => false,
+        'max_age'          => 600,
+        's_maxage'         => 600,
+        'immutable'        => true,
+        'last_modified'    => new \DateTime(),
+        'etag'             => 'abcdef'
     ]);
 
     // it is equivalent to the following code
     $response->setPublic();
+    $response->setMaxAge(600);
+    $response->setSharedMaxAge(600);
+    $response->setImmutable();
+    $response->setLastModified(new \DateTime());
     $response->setEtag('abcde');
-    $response->setLastModified($date);
-    $response->setMaxAge(10);
-    $response->setSharedMaxAge(10);
 
 When using the validation model, the ``isNotModified()`` method allows you to
 cut on the response time by short-circuiting the response generation as early as
diff --git a/http_cache.rst b/http_cache.rst
index 6a09fbfa7c9..fab62790956 100644
--- a/http_cache.rst
+++ b/http_cache.rst
@@ -344,12 +344,18 @@ Additionally, most cache-related HTTP headers can be set via the single
 
     // sets cache settings in one call
     $response->setCache([
-        'etag'          => $etag,
-        'last_modified' => $date,
-        'max_age'       => 10,
-        's_maxage'      => 10,
-        'public'        => true,
-        // 'private'    => true,
+        'must_revalidate'  => false,
+        'no_cache'         => false,
+        'no_store'         => false,
+        'no_transform'     => false,
+        'public'           => true,
+        'private'          => false,
+        'proxy_revalidate' => false,
+        'max_age'          => 600,
+        's_maxage'         => 600,
+        'immutable'        => true,
+        'last_modified'    => new \DateTime(),
+        'etag'             => 'abcdef'
     ]);
 
 Cache Invalidation