Skip to content

Commit bf71611

Browse files
committed
feature #8696 Update HttpCache kernel documentation for Symfony 4 (michaelperrin)
This PR was merged into the 4.0 branch. Discussion ---------- Update HttpCache kernel documentation for Symfony 4 #SymfonyConHackday2017 I am not entirely sure that we should document this way (creating a `src/CacheKernel.php` file as I propose here). Feel free to comment :) Commits ------- b15dba2 Update HttpCache kernel documentation for Symfony 4
2 parents 87d312a + b15dba2 commit bf71611

File tree

4 files changed

+28
-24
lines changed

4 files changed

+28
-24
lines changed

configuration/front_controllers_and_kernel.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ to `decorate`_ the kernel with additional features. Examples include:
4141

4242
* Configuring the autoloader or adding additional autoloading mechanisms;
4343
* Adding HTTP level caching by wrapping the kernel with an instance of
44-
:ref:`AppCache <symfony-gateway-cache>`;
44+
:ref:`HttpCache <symfony-gateway-cache>`;
4545
* Enabling the :doc:`Debug Component </components/debug>`.
4646

4747
You can choose the front controller that's used by adding it in the URL, like:

http_cache.rst

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -77,23 +77,27 @@ but is a great way to start.
7777

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

80-
Enabling the proxy is easy: each application comes with a caching kernel (``AppCache``)
81-
that wraps the default one (``AppKernel``). The caching Kernel *is* the reverse
82-
proxy.
80+
To enable the proxy, first create a caching kernel::
8381

84-
To enable caching, modify the code of your front controller. You can also make these
85-
changes to ``index.php`` to add caching to the ``dev`` environment::
82+
// src/CacheKernel.php
83+
use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
84+
85+
class CacheKernel extends HttpCache
86+
{
87+
}
88+
89+
Modify the code of your front controller to wrap the default kernel into the
90+
caching kernel:
91+
92+
.. code-block:: diff
8693
8794
// public/index.php
88-
use Symfony\Component\HttpFoundation\Request;
8995
9096
// ...
91-
$kernel = new AppKernel('prod', false);
92-
$kernel->loadClassCache();
97+
$kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', $_SERVER['APP_DEBUG'] ?? ('prod' !== ($_SERVER['APP_ENV'] ?? 'dev')));
9398
94-
// add (or uncomment) this new line!
95-
// wrap the default Kernel with the AppCache one
96-
$kernel = new AppCache($kernel);
99+
+ // Wrap the default Kernel with the CacheKernel one
100+
+ $kernel = new CacheKernel($kernel);
97101
98102
$request = Request::createFromGlobals();
99103
// ...
@@ -115,15 +119,15 @@ from your application and returning them to the client.
115119

116120
error_log($kernel->getLog());
117121

118-
The ``AppCache`` object has a sensible default configuration, but it can be
122+
The ``CacheKernel`` object has a sensible default configuration, but it can be
119123
finely tuned via a set of options you can set by overriding the
120124
:method:`Symfony\\Bundle\\FrameworkBundle\\HttpCache\\HttpCache::getOptions`
121125
method::
122126

123-
// app/AppCache.php
127+
// src/CacheKernel.php
124128
use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
125129

126-
class AppCache extends HttpCache
130+
class CacheKernel extends HttpCache
127131
{
128132
protected function getOptions()
129133
{
@@ -150,7 +154,7 @@ information about cache hits and misses.
150154
website or when you deploy your website to a shared host where you cannot
151155
install anything beyond PHP code. But being written in PHP, it cannot
152156
be as fast as a proxy written in C.
153-
157+
154158
Fortunately, since all reverse proxies are effectively the same, you should
155159
be able to switch to something more robust - like Varnish - without any problems.
156160
See :doc:`How to use Varnish </http_cache/varnish>`
@@ -192,7 +196,7 @@ These four headers are used to help cache your responses via *two* different mod
192196

193197
All of the HTTP headers you'll read about are *not* invented by Symfony! They're
194198
part of an HTTP specification that's used by sites all over the web. To dig deeper
195-
into HTTP Caching, check out the documents `RFC 7234 - Caching`_ and
199+
into HTTP Caching, check out the documents `RFC 7234 - Caching`_ and
196200
`RFC 7232 - Conditional Requests`_.
197201

198202
As a web developer, you are strongly urged to read the specification. Its

http_cache/cache_invalidation.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,17 +47,17 @@ the word "PURGE" is a convention, technically this can be any string) instead
4747
of ``GET`` and make the cache proxy detect this and remove the data from the
4848
cache instead of going to the application to get a response.
4949

50-
Here is how you can configure the Symfony reverse proxy to support the
51-
``PURGE`` HTTP method::
50+
Here is how you can configure the Symfony reverse proxy (See :doc:`/http_cache`)
51+
to support the ``PURGE`` HTTP method::
5252

53-
// app/AppCache.php
53+
// src/CacheKernel.php
5454

5555
use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
5656
use Symfony\Component\HttpFoundation\Request;
5757
use Symfony\Component\HttpFoundation\Response;
5858
// ...
5959

60-
class AppCache extends HttpCache
60+
class CacheKernel extends HttpCache
6161
{
6262
protected function invalidate(Request $request, $catch = false)
6363
{

reference/configuration/framework.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -174,17 +174,17 @@ named ``kernel.http_method_override``.
174174

175175
.. caution::
176176

177-
If you're using the :ref:`AppCache Reverse Proxy <symfony2-reverse-proxy>`
177+
If you're using the :ref:`HttpCache Reverse Proxy <symfony2-reverse-proxy>`
178178
with this option, the kernel will ignore the ``_method`` parameter,
179179
which could lead to errors.
180180

181181
To fix this, invoke the ``enableHttpMethodParameterOverride()`` method
182182
before creating the ``Request`` object::
183183

184-
// web/app.php
184+
// public/index.php
185185

186186
// ...
187-
$kernel = new AppCache($kernel);
187+
$kernel = new CacheKernel($kernel);
188188

189189
Request::enableHttpMethodParameterOverride(); // <-- add this line
190190
$request = Request::createFromGlobals();

0 commit comments

Comments
 (0)