[Cache] Doc forkable adapters, aka namespace based invalidation

Author: nicolas-grekas

components/cache/cache_invalidation.rst

@@ -1,6 +1,7 @@
 .. index::
    single: Cache; Invalidation
    single: Cache; Tags
+   single: Cache; Namespaces
 
 Cache Invalidation
 ==================
@@ -10,13 +11,14 @@ change in the state of your model. The most basic kind of invalidation is direct
 items deletion. But when the state of a primary resource has spread accross
 several cached items, keeping them in sync can be difficult.
 
-The Symfony Cache component provides two mechanisms to help solve this problem:
+The Symfony Cache component provides three mechanisms to help solve this problem:
 
 * Tags based invalidation for managing data dependencies;
+* Namespace based invalidation for context dependent data;
 * Expiration based invalidation for time related dependencies.
 
 .. versionadded:: 3.2
-    Tags based invalidation was introduced in Symfony 3.2.
+    Tags and namespace based invalidation was introduced in Symfony 3.2.
 
 Using Cache Tags
 ----------------
@@ -81,6 +83,39 @@ your fronts and have very fast invalidation checks::
         new RedisAdapter('redis://localhost')
     );
 
+Using Cache Namespaces
+----------------------
+
+By using adapters that implement the
+:method:`Symfony\\Component\\Cache\\Adapter\\ForkableAdapterInterface::fork`
+method, you can create context-dependent variations of your cached items.
+
+Forks work by cloning existing adapters into new adapters that share everything
+with their parent (esp. the data store connection) but add a ``$namespace``
+prefix to all their keys, in a way that makes a cache key in a forked adapter
+unable to collide with the same key in its parent adapter.
+
+You can use forks everywhere you would otherwise manually prefix your cache keys
+in your code. A typical example is storing different HTML pages per e.g.
+``Vary: User-Agent`` or ``Vary: Accept-Encoding`` HTTP headers::
+
+    $perUserAgentCache = $httpCache->fork($varyingUserAgent);
+    $perAcceptEncodingPerUserAgentCache = $perUserAgentCache->fork($varyingAcceptEncoding);
+
+    // Here, several $pageItem objects can be stored per $someUrl:
+    // one per $varyingUserAgent and per $varyingAcceptEncoding
+    $pageItem = $perAcceptEncodingPerUserAgentCache->getItem($someUrl);
+
+Forks are organized in subtrees so that clearing one branch of the tree clears all
+sub-trees recursively::
+
+    $httpCache->clear();
+    // both $perUserAgentCache and $perAcceptEncodingPerUserAgentCache are now also empty
+
+.. note::
+
+    Invalidating by tags affects all parents and children forks.
+
 Using Cache Expiration
 ----------------------