Skip to content

Commit 61a855b

Browse files
nicolas-grekasjaviereguiluz
nicolas-grekas
authored and
javiereguiluz
committed
Update section about http cache
1 parent f6d8853 commit 61a855b

File tree

2 files changed

+115
-64
lines changed

2 files changed

+115
-64
lines changed

‎http_cache.rst‎

Lines changed: 19 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -77,79 +77,35 @@ but it is a great way to start.
7777

7878
For details on setting up Varnish, see :doc:`/http_cache/varnish`.
7979

80-
To enable the proxy, first create a caching kernel::
80+
To enable the proxy for the ``prod`` env, enable the ``framework.http_cache`` setting:
8181

82-
// src/CacheKernel.php
83-
namespace App;
82+
.. configuration-block::
8483

85-
use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
84+
.. code-block:: yaml
8685
87-
class CacheKernel extends HttpCache
88-
{
89-
}
90-
91-
Modify the code of your front controller to wrap the default kernel into the
92-
caching kernel:
86+
# config/packages/framework.yaml
87+
when@prod:
88+
framework:
89+
http_cache: true
9390
94-
.. code-block:: diff
91+
.. code-block:: php
9592
96-
// public/index.php
93+
// config/packages/framework.php
94+
use Symfony\Config\FrameworkConfig;
9795
98-
+ use App\CacheKernel;
99-
use App\Kernel;
100-
101-
// ...
102-
$kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
103-
+ // Wrap the default Kernel with the CacheKernel one in 'prod' environment
104-
+ if ('prod' === $kernel->getEnvironment()) {
105-
+ return new CacheKernel($kernel);
106-
+ }
107-
return $kernel;
96+
return static function (FrameworkConfig $framework) use ($env) {
97+
if ('prod' === $env) {
98+
$framework->httpCache()->enabled(true);
99+
}
100+
};
108101
109-
110-
The caching kernel will immediately act as a reverse proxy: caching responses
102+
The kernel will immediately act as a reverse proxy: caching responses
111103
from your application and returning them to the client.
112104

113-
.. caution::
114-
115-
If you're using the :ref:`framework.http_method_override <configuration-framework-http_method_override>`
116-
option to read the HTTP method from a ``_method`` parameter, see the
117-
above link for a tweak you need to make.
118-
119-
.. tip::
120-
121-
The cache kernel has a special ``getLog()`` method that returns a string
122-
representation of what happened in the cache layer. In the development
123-
environment, use it to debug and validate your cache strategy::
124-
125-
error_log($kernel->getLog());
126-
127-
The ``CacheKernel`` object has a sensible default configuration, but it can be
128-
finely tuned via a set of options you can set by overriding the
129-
:method:`Symfony\\Bundle\\FrameworkBundle\\HttpCache\\HttpCache::getOptions`
130-
method::
131-
132-
// src/CacheKernel.php
133-
namespace App;
134-
135-
use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
136-
137-
class CacheKernel extends HttpCache
138-
{
139-
protected function getOptions(): array
140-
{
141-
return [
142-
'default_ttl' => 0,
143-
// ...
144-
];
145-
}
146-
}
147-
148-
For a full list of the options and their meaning, see the
149-
:method:`HttpCache::__construct() documentation <Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache::__construct>`.
105+
The proxy has a sensible default configuration, but it can be
106+
finely tuned via `a set of options<configuration-framework-http_cache>`.
150107

151-
When you're in debug mode (the second argument of ``Kernel`` constructor in the
152-
front controller is ``true``), Symfony automatically adds an ``X-Symfony-Cache``
108+
When in debug mode, Symfony automatically adds an ``X-Symfony-Cache``
153109
header to the response. You can also use the ``trace_level`` config
154110
option and set it to either ``none``, ``short`` or ``full`` to
155111
add this information.

‎reference/configuration/framework.rst‎

Lines changed: 96 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,102 @@ will invalidate all signed URIs and Remember Me cookies. That's why, after
5353
changing this value, you should regenerate the application cache and log
5454
out all the application users.
5555

56-
.. _configuration-framework-http_method_override:
56+
.. _configuration-framework-http_cache:
57+
58+
http_cache
59+
~~~~~~~~~~
60+
61+
.. versionadded:: 5.2
62+
63+
The ``http_cache`` option was introduced in Symfony 5.2.
64+
65+
enabled
66+
.......
67+
68+
**type**: ``boolean`` **default**: ``false``
69+
70+
debug
71+
.....
72+
73+
**type**: ``boolean`` **default**: ``%kernel.debug%``
74+
75+
If true, exceptions are thrown when things go wrong. Otherwise, the cache will
76+
try to carry on and deliver a meaningful response.
77+
78+
trace_level
79+
...........
80+
81+
**type**: ``string`` **possible values**: ``'none'``, ``'short'`` or ``'full'``
82+
83+
For 'short', a concise trace of the main request will be added as an HTTP header.
84+
'full' will add traces for all requests (including ESI subrequests).
85+
(default: 'full' if in debug; 'none' otherwise)
86+
87+
trace_header
88+
............
89+
90+
**type**: ``string``
91+
92+
Header name to use for traces. (default: X-Symfony-Cache)
93+
94+
default_ttl
95+
...........
96+
97+
**type**: ``integer``
98+
99+
The number of seconds that a cache entry should be considered fresh when no
100+
explicit freshness information is provided in a response. Explicit
101+
Cache-Control or Expires headers override this value. (default: 0)
102+
103+
private_headers
104+
...............
105+
106+
**type**: ``array``
107+
108+
Set of request headers that trigger "private" cache-control behavior on responses
109+
that don't explicitly state whether the response is public or private via a
110+
Cache-Control directive. (default: Authorization and Cookie)
111+
112+
allow_reload
113+
............
114+
115+
**type**: ``string``
116+
117+
Specifies whether the client can force a cache reload by including a
118+
Cache-Control "no-cache" directive in the request. Set it to ``true``
119+
for compliance with RFC 2616. (default: false)
120+
121+
allow_revalidate
122+
................
123+
124+
**type**: ``string``
125+
126+
Specifies whether the client can force a cache revalidate by including a
127+
Cache-Control "max-age=0" directive in the request. Set it to ``true``
128+
for compliance with RFC 2616. (default: false)
129+
130+
stale_while_revalidate
131+
......................
132+
133+
**type**: ``integer``
134+
135+
Specifies the default number of seconds (the granularity is the second as the
136+
Response TTL precision is a second) during which the cache can immediately return
137+
a stale response while it revalidates it in the background (default: 2).
138+
This setting is overridden by the stale-while-revalidate HTTP Cache-Control
139+
extension (see RFC 5861).
140+
141+
stale_if_error
142+
..............
143+
144+
**type**: ``integer``
145+
146+
Specifies the default number of seconds (the granularity is the second) during
147+
which the cache can serve a stale response when an error is encountered
148+
(default: 60). This setting is overridden by the stale-if-error HTTP
149+
Cache-Control extension (see RFC 5861).
150+
151+
.. _configuration-framework-http_method_override:
57152

58153
http_method_override
59154
~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)