minor symfony#12770 [Cache] Expand the docs about the cache chain (javiereguiluz)

javiereguiluz · javiereguiluz · commit 87753845471c · 2019-12-07T20:48:02.000+01:00
This PR was merged into the 3.4 branch. Discussion ---------- [Cache] Expand the docs about the cache chain I asked @nicolas-grekas about the Cache chains and he explained to me lots of nice things about this ... so I think we could improve the docs a bit to mention all this. Commits ------- 1227f8b [Cache] Expand the docs about the cache chain
diff --git a/cache.rst b/cache.rst
@@ -397,11 +397,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::
 
