Update section about http cache

http_cache.rst

@@ -77,79 +77,35 @@ but it is a great way to start.
 
     For details on setting up Varnish, see :doc:`/http_cache/varnish`.
 
-To enable the proxy, first create a caching kernel::
+To enable the proxy for the ``prod`` env, enable the ``framework.http_cache`` setting:
 
-    // src/CacheKernel.php
-    namespace App;
+.. configuration-block::
 
-    use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
+    .. code-block:: yaml
 
-    class CacheKernel extends HttpCache
-    {
-    }
-
-Modify the code of your front controller to wrap the default kernel into the
-caching kernel:
+        # config/packages/framework.yaml
+        when@prod:
+            framework:
+                http_cache: true
 
-.. code-block:: diff
+    .. code-block:: php
 
-      // public/index.php
+        // config/packages/framework.php
+        use Symfony\Config\FrameworkConfig;
 
-    + use App\CacheKernel;
-      use App\Kernel;
-
-    // ...
-    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
-    + // Wrap the default Kernel with the CacheKernel one in 'prod' environment
-    + if ('prod' === $kernel->getEnvironment()) {
-    +     return new CacheKernel($kernel);
-    + }
-    return $kernel;
+        return static function (FrameworkConfig $framework) use ($env) {
+            if ('prod' === $env) {
+                $framework->httpCache()->enabled(true);
+            }
+        };
 
-
-The caching kernel will immediately act as a reverse proxy: caching responses
+The kernel will immediately act as a reverse proxy: caching responses
 from your application and returning them to the client.
 
-.. caution::
-
-    If you're using the :ref:`framework.http_method_override <configuration-framework-http_method_override>`
-    option to read the HTTP method from a ``_method`` parameter, see the
-    above link for a tweak you need to make.
-
-.. tip::
-
-    The cache kernel has a special ``getLog()`` method that returns a string
-    representation of what happened in the cache layer. In the development
-    environment, use it to debug and validate your cache strategy::
-
-        error_log($kernel->getLog());
-
-The ``CacheKernel`` object has a sensible default configuration, but it can be
-finely tuned via a set of options you can set by overriding the
-:method:`Symfony\\Bundle\\FrameworkBundle\\HttpCache\\HttpCache::getOptions`
-method::
-
-    // src/CacheKernel.php
-    namespace App;
-
-    use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
-
-    class CacheKernel extends HttpCache
-    {
-        protected function getOptions(): array
-        {
-            return [
-                'default_ttl' => 0,
-                // ...
-            ];
-        }
-    }
-
-For a full list of the options and their meaning, see the
-:method:`HttpCache::__construct() documentation <Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache::__construct>`.
+The proxy has a sensible default configuration, but it can be
+finely tuned via `a set of options<configuration-framework-http_cache>`.
 
-When you're in debug mode (the second argument of ``Kernel`` constructor in the
-front controller is ``true``), Symfony automatically adds an ``X-Symfony-Cache``
+When in debug mode, Symfony automatically adds an ``X-Symfony-Cache``
 header to the response. You can also use the ``trace_level`` config
 option and set it to either ``none``, ``short`` or ``full`` to
 add this information.

reference/configuration/framework.rst

@@ -53,7 +53,102 @@ will invalidate all signed URIs and Remember Me cookies. That's why, after
 changing this value, you should regenerate the application cache and log
 out all the application users.
 
-.. _configuration-framework-http_method_override:
+.. _configuration-framework-http_cache:
+
+http_cache
+~~~~~~~~~~
+
+.. versionadded:: 5.2
+
+    The ``http_cache`` option was introduced in Symfony 5.2.
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``false``
+
+debug
+.....
+
+**type**: ``boolean`` **default**: ``%kernel.debug%``
+
+If true, exceptions are thrown when things go wrong. Otherwise, the cache will
+try to carry on and deliver a meaningful response.
+
+trace_level
+...........
+
+**type**: ``string`` **possible values**: ``'none'``, ``'short'`` or ``'full'``
+
+For 'short', a concise trace of the main request will be added as an HTTP header.
+'full' will add traces for all requests (including ESI subrequests).
+(default: 'full' if in debug; 'none' otherwise)
+
+trace_header
+............
+
+**type**: ``string``
+
+Header name to use for traces. (default: X-Symfony-Cache)
+
+default_ttl
+...........
+
+**type**: ``integer``
+
+The number of seconds that a cache entry should be considered fresh when no
+explicit freshness information is provided in a response. Explicit
+Cache-Control or Expires headers override this value. (default: 0)
+
+private_headers
+...............
+
+**type**: ``array``
+
+Set of request headers that trigger "private" cache-control behavior on responses
+that don't explicitly state whether the response is public or private via a
+Cache-Control directive. (default: Authorization and Cookie)
+
+allow_reload
+............
+
+**type**: ``string``
+
+Specifies whether the client can force a cache reload by including a
+Cache-Control "no-cache" directive in the request. Set it to ``true``
+for compliance with RFC 2616. (default: false)
+
+allow_revalidate
+................
+
+**type**: ``string``
+
+Specifies whether the client can force a cache revalidate by including a
+Cache-Control "max-age=0" directive in the request. Set it to ``true``
+for compliance with RFC 2616. (default: false)
+
+stale_while_revalidate
+......................
+
+**type**: ``integer``
+
+Specifies the default number of seconds (the granularity is the second as the
+Response TTL precision is a second) during which the cache can immediately return
+a stale response while it revalidates it in the background (default: 2).
+This setting is overridden by the stale-while-revalidate HTTP Cache-Control
+extension (see RFC 5861).
+
+stale_if_error
+..............
+
+**type**: ``integer``
+
+Specifies the default number of seconds (the granularity is the second) during
+which the cache can serve a stale response when an error is encountered
+(default: 60). This setting is overridden by the stale-if-error HTTP
+Cache-Control extension (see RFC 5861).
+
+ .. _configuration-framework-http_method_override:
 
 http_method_override
 ~~~~~~~~~~~~~~~~~~~~