[HttpCache] Explain how to extend the HttpCache class

Author: HypeMC

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