8000 Merge branch '5.1' into 5.2 · javiereguiluz/symfony-docs@18dbbc0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 18dbbc0

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '5.1' into 5.2
* 5.1: Added the versionadded directive Added config reference for router.default_uri [symfony#14658] Minor tweaks to cache encryption section [Cache] Document cache encryption using SodiumMarshaller
2 parents a07c802 + 2ed719f commit 18dbbc0

File tree

3 files changed

+101
-0
lines changed

3 files changed

+101
-0
lines changed

‎cache.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -719,3 +719,89 @@ Clear all caches everywhere:
719719
.. code-block:: terminal
720720
721721
$ php bin/console cache:pool:clear cache.global_clearer
722+
723+
Encrypting the Cache
724+
--------------------
725+
726+
.. versionadded:: 5.1
727+
728+
The :class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`
729+
class was introduced in Symfony 5.1.
730+
731+
To encrypt the cache using ``libsodium``, you can use the
732+
:class:`Symfony\\Component\\Cache\\Marshaller\\SodiumMarshaller`.
733+
734+
First, you need to generate a secure key and add it to your :doc:`secret
735+
store </configuration/secrets>` as ``CACHE_DECRYPTION_KEY``:
736+
737+
.. code-block:: terminal
738+
739+
$ php -r 'echo base64_encode(sodium_crypto_box_keypair());'
740+
741+
Then, register the ``SodiumMarshaller`` service using this key:
742+
743+
.. configuration-block::
744+
745+
.. code-block:: yaml
746+
747+
# config/packages/cache.yaml
748+
749+
# ...
750+
services:
751+
Symfony\Component\Cache\Marshaller\SodiumMarshaller:
752+
decorates: cache.default_marshaller
753+
arguments:
754+
- ['%env(base64:CACHE_DECRYPTION_KEY)%']
755+
# use multiple keys in order to rotate them
756+
#- ['%env(base64:CACHE_DECRYPTION_KEY)%', '%env(base64:OLD_CACHE_DECRYPTION_KEY)%']
757+
- '@Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner'
758+
759+
.. code-block:: xml
760+
761+
<!-- config/packages/cache.xml -->
762+
<?xml version="1.0" encoding="UTF-8" ?>
763+
<container xmlns="http://symfony.com/schema/dic/services"
764+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
765+
xmlns:framework="http://symfony.com/schema/dic/symfony"
766+
xsi:schemaLocation="http://symfony.com/schema/dic/services
767+
https://symfony.com/schema/dic/services/services-1.0.xsd
768+
http://symfony.com/schema/dic/symfony
769+
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
770+
771+
<!-- ... -->
772+
773+
<services>
774+
<service id="Symfony\Component\Cache\Marshaller\SodiumMarshaller" decorates="cache.default_marshaller">
775+
<argument type="collection">
776+
<argument>env(base64:CACHE_DECRYPTION_KEY)</argument>
777+
<!-- use multiple keys in order to rotate them -->
778+
<!-- <argument>env(base64:OLD_CACHE_DECRYPTION_KEY)</argument> -->
779+
</argument>
780+
<argument type="service" id="Symfony\Component\Cache\Marshaller\SodiumMarshaller.inner"/>
781+
</service>
782+
</services>
783+
</container>
784+
785+
.. code-block:: php
786+
787+
// config/packages/cache.php
788+
use Symfony\Component\Cache\Marshaller\SodiumMarshaller;
789+
use Symfony\Component\DependencyInjection\ChildDefinition;
790+
use Symfony\Component\DependencyInjection\Reference;
791+
792+
// ...
793+
$container->setDefinition(SodiumMarshaller::class, new ChildDefinition('cache.default_marshaller'))
794+
->addArgument(['env(base64:CACHE_DECRYPTION_KEY)'])
795+
// use multiple keys in order to rotate them
796+
//->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
797+
->addArgument(new Reference(SodiumMarshaller::class.'.inner'));
798+
799+
.. caution::
800+
801+
This will encrypt the values of the cache items, but not the cache keys. Be
802+
careful not the leak sensitive data in the keys.
803+
804+
When configuring multiple keys, the first key will be used for reading and
805+
writing, and the additional key(s) will only be used for reading. Once all
806+
cache items encrypted with the old key have expired, you can remove
807+
``OLD_CACHE_DECRYPTION_KEY`` completely.

‎reference/configuration/framework.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,7 @@ Configuration
217217

218218
* `router`_
219219

220+
* `default_uri`_
220221
* `http_port`_
221222
* `https_port`_
222223
* `resource`_
@@ -1304,6 +1305,18 @@ The type of the resource to hint the loaders about the format. This isn't
13041305
needed when you use the default routers with the expected file extensions
13051306
(``.xml``, ``.yaml``, ``.php``).
13061307

1308+
default_uri
1309+
...........
1310+
1311+
**type**: ``string``
1312+
1313+
.. versionadded:: 5.1
1314+
1315+
The ``default_uri`` option was introduced in Symfony 5.1.
1316+
1317+
The default URI used to generate URLs in a non-HTTP context (see
1318+
:ref:`Generating URLs in Commands <router-generate-urls-commands>`).
1319+
13071320
http_port
13081321
.........
13091322

‎routing.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2429,6 +2429,8 @@ If you need to generate URLs dynamically or if you are using pure JavaScript
24292429
code, this solution doesn't work. In those cases, consider using the
24302430
`FOSJsRoutingBundle`_.
24312431

2432+
.. _router-generate-urls-commands:
2433+
24322434
Generating URLs in Commands
24332435
~~~~~~~~~~~~~~~~~~~~~~~~~~~
24342436

0 commit comments

Comments
 (0)
0