feature #17972 [HttpCache] Explain how to extend the HttpCache class (HypeMC)

This PR was merged into the 5.4 branch.

Discussion
----------

[HttpCache] Explain how to extend the `HttpCache` class

Followup to #16402.

In versions of Symfony prior to 5.4 the caching kernel was enabled by wrapping the default kernel into it inside the front controller, eg:

```php
// public/index.php
use App\CacheKernel;
use App\Kernel;

// ...
$kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
// Wrap the default Kernel with the CacheKernel one in 'prod' environment
if ('prod' === $kernel->getEnvironment()) {
    $kernel = new CacheKernel($kernel);
}
```

Starting from version 5.4 this was changed to be done through the configuration:

```yaml
# config/packages/framework.yaml
when@prod:
    framework:
        http_cache: true
```

However, it was never explained how the caching kernel can be extended in this case. Decorating the `http_cache` service seems like the best option.

Commits
-------

34809dd [HttpCache] Explain how to extend the HttpCache class

Author: OskarStark

http_cache/cache_invalidation.rst

@@ -47,8 +47,9 @@ the word "PURGE" is a convention, technically this can be any string) instead
 of ``GET`` and make the cache proxy detect this and remove the data from the
 cache instead of going to the application to get a response.
 
-Here is how you can configure the Symfony reverse proxy (See :doc:`/http_cache`)
-to support the ``PURGE`` HTTP method::
+Here is how you can configure the :ref:`Symfony reverse proxy <symfony-gateway-cache>`
+to support the ``PURGE`` HTTP method. First create a caching kernel that overrides the
+:method:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache::invalidate` method::
 
     // src/CacheKernel.php
     namespace App;
@@ -84,6 +85,58 @@ to support the ``PURGE`` HTTP method::
         }
     }
 
+Then, register the class as a service that :doc:`decorates </service_container/service_decoration>`
+``http_cache``::
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\CacheKernel:
+                decorates: http_cache
+                arguments:
+                    - '@kernel'
+                    - '@http_cache.store'
+                    - '@?esi'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd"
+        >
+            <service id="App\CacheKernel" decorates="http_cache">
+                <argument type="service" id="kernel"/>
+                <argument type="service" id="http_cache.store"/>
+                <argument type="service" id="esi" on-invalid="null"/>
+            </service>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\CacheKernel;
+
+        return function (ContainerConfigurator $containerConfigurator) {
+            $services = $containerConfigurator->services();
+
+            $services->set(CacheKernel::class)
+                ->decorate('http_cache')
+                ->args([
+                    service('kernel'),
+                    service('http_cache.store'),
+                    service('esi')->nullOnInvalid(),
+                ])
+            ;
+        };
+
 .. caution::
 
     You must protect the ``PURGE`` HTTP method somehow to avoid random people