Merge branch '5.4' into 6.3

* 5.4:
  [Cache] Add integration with Messenger
  [HttpKernel] Auto-register kernel as an extension

Author: javiereguiluz

cache.rst

@@ -846,3 +846,148 @@ When configuring multiple keys, the first key will be used for reading and
 writing, and the additional key(s) will only be used for reading. Once all
 cache items encrypted with the old key have expired, you can completely remove
 ``OLD_CACHE_DECRYPTION_KEY``.
+
+Computing Cache Values Asynchronously
+-------------------------------------
+
+.. versionadded:: 5.2
+
+    The feature to compute cache values asynchronously was introduced in Symfony 5.2.
+
+The Cache component uses the `probabilistic early expiration`_ algorithm to
+protect against the :ref:`cache stampede <cache_stampede-prevention>` problem.
+This means that some cache items are elected for early-expiration while they are
+still fresh.
+
+By default, expired cache items are computed synchronously. However, you can
+compute them asynchronously by delegating the value computation to a background
+worker using the :doc:`Messenger component </components/messenger>`. In this case,
+when an item is queried, its cached value is immediately returned and a
+:class:`Symfony\\Component\\Cache\\Messenger\\EarlyExpirationMessage` is
+dispatched through a Messenger bus.
+
+When this message is handled by a message consumer, the refreshed cache value is
+computed asynchronously. The next time the item is queried, the refreshed value
+will be fresh and returned.
+
+First, create a service that will compute the item's value::
+
+    // src/Cache/CacheComputation.php
+    namespace App\Cache;
+
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    class CacheComputation
+    {
+        public function compute(ItemInterface $item): string
+        {
+            $item->expiresAfter(5);
+
+            // this is just a random example; here you must do your own calculation
+            return sprintf('#%06X', mt_rand(0, 0xFFFFFF));
+        }
+    }
+
+This cache value will be requested from a controller, another service, etc.
+In the following example, the value is requested from a controller::
+
+    // src/Controller/CacheController.php
+    namespace App\Controller;
+
+    use App\Cache\CacheComputation;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\Routing\Annotation\Route;
+    use Symfony\Contracts\Cache\CacheInterface;
+    use Symfony\Contracts\Cache\ItemInterface;
+
+    class CacheController extends AbstractController
+    {
+        /**
+         * @Route("/cache", name="cache")
+         */
+        public function index(CacheInterface $asyncCache): Response
+        {
+            // pass to the cache the service method that refreshes the item
+            $cachedValue = $cache->get('my_value', [CacheComputation::class, 'compute'])
+
+            // ...
+        }
+    }
+
+Finally, configure a new cache pool (e.g. called ``async.cache``) that will use
+a message bus to compute values in a worker:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            cache:
+                pools:
+                    async.cache:
+                        messenger_bus: async_bus
+
+            messenger:
+                transports:
+                    async_bus: '%env(MESSENGER_TRANSPORT_DSN)%'
+                routing:
+                    Symfony\Component\Cache\Messenger\Message\EarlyExpirationMessage: async_bus
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.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"
+           xmlns:framework="http://symfony.com/schema/dic/symfony"
+           xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+            <framework:config>
+                <framework:cache>
+                    <framework:pool name="async.cache" early-expiration-message-bus="async_bus"/>
+                </framework:cache>
+
+                <framework:messenger>
+                    <framework:transport name="async_bus">%env(MESSENGER_TRANSPORT_DSN)%</framework:transport>
+                    <framework:routing message-class="Symfony\Component\Cache\Messenger\Message\EarlyExpirationMessage">
+                        <framework:sender service="async_bus"/>
+                    </framework:routing>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/framework/framework.php
+        use function Symfony\Component\DependencyInjection\Loader\Configurator\env;
+        use Symfony\Component\Cache\Messenger\EarlyExpirationMessage;
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework): void {
+            $framework->cache()
+                ->pool('async.cache')
+                    ->earlyExpirationMessageBus('async_bus');
+
+            $framework->messenger()
+                ->transport('async_bus')
+                    ->dsn(env('MESSENGER_TRANSPORT_DSN'))
+                ->routing(EarlyExpirationMessage::class)
+                    ->senders(['async_bus']);
+        };
+
+You can now start the consumer:
+
+.. code-block:: terminal
+
+    $ php bin/console messenger:consume async_bus
+
+That's it! Now, whenever an item is queried from this cache pool, its cached
+value will be returned immediately. If it is elected for early-expiration, a
+message will be sent through to bus to schedule a background computation to refresh
+the value.
+
+.. _`probabilistic early expiration`: https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration

components/cache.rst

@@ -84,6 +84,8 @@ generate and return the value::
     Use cache tags to delete more than one key at the time. Read more at
     :doc:`/components/cache/cache_invalidation`.
 
+.. _cache_stampede-prevention:
+
 Stampede Prevention
 ~~~~~~~~~~~~~~~~~~~
 

configuration/micro_kernel_trait.rst

@@ -159,7 +159,18 @@ Adding Interfaces to "Micro" Kernel
 When using the ``MicroKernelTrait``, you can also implement the
 ``CompilerPassInterface`` to automatically register the kernel itself as a
 compiler pass as explained in the dedicated
-:ref:`compiler pass section <kernel-as-compiler-pass>`.
+:ref:`compiler pass section <kernel-as-compiler-pass>`. If the
+:class:`Symfony\\Component\\DependencyInjection\\Extension\\ExtensionInterface`
+is implemented when using the ``MicroKernelTrait``, then the kernel will
+be automatically registered as an extension. You can learn more about it in
+the dedicated section about
+:ref:`managing configuration with extensions <components-dependency-injection-extension>`.
+
+.. versionadded:: 5.2
+
+    The automatic registration of the kernel as an extension when implementing the
+    :class:`Symfony\\Component\\DependencyInjection\\Extension\\ExtensionInterface`
+    was introduced in Symfony 5.2.
 
 It is also possible to implement the ``EventSubscriberInterface`` to handle
 events directly from the kernel, again it will be registered automatically::