From 61a855b01482b6317ac6aa3db7efaf471863a203 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Sun, 16 Jan 2022 15:26:16 +0100 Subject: [PATCH] Update section about http cache --- http_cache.rst | 82 ++++++---------------- reference/configuration/framework.rst | 97 ++++++++++++++++++++++++++- 2 files changed, 115 insertions(+), 64 deletions(-) diff --git a/http_cache.rst b/http_cache.rst index 51d42a5cf71..57750e4b9c8 100644 --- a/http_cache.rst +++ b/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 ` - 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 `. +The proxy has a sensible default configuration, but it can be +finely tuned via `a set of options`. -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. diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 434952b7da6..b3e72757128 100644 --- a/reference/configuration/framework.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~