Merge branch '5.0'

* 5.0:
  [Cache] Fixed a minor RST syntax issue
  [Cache] Expand the docs about the cache chain
  Explain the prefix used for expressions in YAML files
  Minor tweak in a security expression explanation

Author: javiereguiluz

cache.rst

@@ -370,11 +370,21 @@ and use that when configuring the pool.
 Creating a Cache Chain
 ----------------------
 
-Different cache adapters have different strengths and weaknesses. Some might be really
-quick but small and some may be able to contain a lot of data but are quite slow.
-To get the best of both worlds you may use a chain of adapters. The idea is to
-first look at the quick adapter and then move on to slower adapters. In the worst
-case the value needs to be recalculated.
+Different cache adapters have different strengths and weaknesses. Some might be
+really quick but optimized to store small items and some may be able to contain
+a lot of data but are quite slow. To get the best of both worlds you may use a
+chain of adapters.
+
+A cache chain combines several cache pools into a single one. When storing an
+item in a cache chain, Symfony stores it in all pools sequentially. When
+retrieving an item, Symfony tries to get it from the first pool. If it's not
+found, it tries the next pools until the item is found or an exception is thrown.
+Because of this behavior, it's recommended to define the adapters in the chain
+in order from the fastest to the slowest.
+
+If an error happens when storing an item in a pool, Symfony stores it in the
+other pools and no exception is thrown. Later, when the item is retrieved,
+Symfony stores the item automatically in all the missing pools.
 
 .. configuration-block::
 
@@ -470,7 +480,7 @@ the same key could be invalidate with one function call::
         }
     }
 
-The cache adapter needs to implement :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface``
+The cache adapter needs to implement :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`
 to enable this feature. This could be added by using the following configuration.
 
 .. configuration-block::

security/expressions.rst

@@ -39,9 +39,9 @@ Inside the expression, you have access to a number of variables:
 ``user``
     The user object (or the string ``anon`` if you're not authenticated).
 ``roles``
-    The array of roles the user has, including from the
-    :ref:`role hierarchy <security-role-hierarchy>` but not including the
-    ``IS_AUTHENTICATED_*`` attributes (see the functions below).
+    The array of roles the user has. This array includes any roles granted
+    indirectly via the :ref:`role hierarchy <security-role-hierarchy>` but it
+    does not include the ``IS_AUTHENTICATED_*`` attributes (see the functions below).
 ``object``
     The object (if any) that's passed as the second argument to ``isGranted()``.
 ``token``

service_container/expression_language.rst

@@ -28,6 +28,7 @@ to another service: ``App\Mailer``. One way to do this is with an expression:
             App\Mail\MailerConfiguration: ~
 
             App\Mailer:
+                # the '@=' prefix is required when using expressions for arguments in YAML files
                 arguments: ['@=service("App\\Mail\\MailerConfiguration").getMailerMethod()']
                 # when using double-quoted strings, the backslash needs to be escaped twice (see https://yaml.org/spec/1.2/spec.html#id2787109)
                 # arguments: ["@=service('App\\\\Mail\\\\MailerConfiguration').getMailerMethod()"]
@@ -89,6 +90,7 @@ via a ``container`` variable. Here's another example:
         # config/services.yaml
         services:
             App\Mailer:
+                # the '@=' prefix is required when using expressions for arguments in YAML files
                 arguments: ["@=container.hasParameter('some_param') ? parameter('some_param') : 'default_value'"]
 
     .. code-block:: xml