Merge branch '5.1' into 5.2

* 5.1:
  Added the versionadded directive
  Added config reference for router.default_uri
  [#14658] Minor tweaks to cache encryption section
  [Cache] Document cache encryption using SodiumMarshaller

Author: javiereguiluz

cache.rst

@@ -719,3 +719,89 @@ Clear all caches everywhere:
 .. code-block:: terminal
 
     $ php bin/console cache:pool:clear cache.global_clearer
+
+Encrypting the Cache
+--------------------
+
+.. versionadded:: 5.1
+
+    The :class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`
+    class was introduced in Symfony 5.1.
+
+To encrypt the cache using ``libsodium``, you can use the
+:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`.
+
+First, you need to generate a secure key and add it to your :doc:`secret
+store </configuration/secrets>` as ``CACHE_DECRYPTION_KEY``:
+
+.. code-block:: terminal
+
+    $ php -r 'echo base64_encode(sodium_crypto_box_keypair());'
+
+Then, register the ``SodiumMarshaller`` service using this key:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/cache.yaml
+
+        # ...
+        services:
+            Symfony\Component\Cache\Marshaller\SodiumMarshaller:
+                decorates: cache.default_marshaller
+                arguments:
+                    - ['%env(base64:CACHE_DECRYPTION_KEY)%']
+                    # use multiple keys in order to rotate them
+                    #- ['%env(base64:CACHE_DECRYPTION_KEY)%', '%env(base64:OLD_CACHE_DECRYPTION_KEY)%']
+                    - '@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'
+
+    .. code-block:: xml
+
+        <!-- config/packages/cache.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">
+
+            <!-- ... -->
+
+            <services>
+                <service id="Symfony\Component\Cache\Marshaller\SodiumMarshaller" decorates="cache.default_marshaller">
+                    <argument type="collection">
+                        <argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
+                        <!-- use multiple keys in order to rotate them -->
+                        <!-- <argument>env(base64:OLD_CACHE_DECRYPTION_KEY)</argument> -->
+                    </argument>
+                    <argument type="service" id="Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/cache.php
+        use Symfony\Component\Cache\Marshaller\SodiumMarshaller;
+        use Symfony\Component\DependencyInjection\ChildDefinition;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        // ...
+        $container->setDefinition(SodiumMarshaller::class, new ChildDefinition('cache.default_marshaller'))
+            ->addArgument(['env(base64:CACHE_DECRYPTION_KEY)'])
+            // use multiple keys in order to rotate them
+            //->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
+            ->addArgument(new Reference(SodiumMarshaller::class.'.inner'));
+
+.. caution::
+
+    This will encrypt the values of the cache items, but not the cache keys. Be
+    careful not the leak sensitive data in the keys.
+
+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 remove
+``OLD_CACHE_DECRYPTION_KEY`` completely.

reference/configuration/framework.rst

@@ -217,6 +217,7 @@ Configuration
 
 * `router`_
 
+  * `default_uri`_
   * `http_port`_
   * `https_port`_
   * `resource`_
@@ -1304,6 +1305,18 @@ The type of the resource to hint the loaders about the format. This isn't
 needed when you use the default routers with the expected file extensions
 (``.xml``, ``.yaml``, ``.php``).
 
+default_uri
+...........
+
+**type**: ``string``
+
+.. versionadded:: 5.1
+
+    The ``default_uri`` option was introduced in Symfony 5.1.
+
+The default URI used to generate URLs in a non-HTTP context (see
+:ref:`Generating URLs in Commands <router-generate-urls-commands>`).
+
 http_port
 .........
 

routing.rst

@@ -2429,6 +2429,8 @@ If you need to generate URLs dynamically or if you are using pure JavaScript
 code, this solution doesn't work. In those cases, consider using the
 `FOSJsRoutingBundle`_.
 
+.. _router-generate-urls-commands:
+
 Generating URLs in Commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~