[Cache] Add chapter about invalidation, tags, etc.

Author: nicolas-grekas

components/cache.rst

@@ -6,7 +6,7 @@
 The Cache Component
 ===================
 
-    The Cache component provides a strict `PSR-6`_ implementation for adding
+    The Cache component provides an extended `PSR-6`_ implementation for adding
     cache to your applications. It is designed to have a low overhead and it
     ships with ready to use adapters for the most common caching backends.
 
@@ -42,7 +42,7 @@ meaning of some key concepts:
 Basic Usage
 -----------
 
-This component is a strict implementation of `PSR-6`_, which means that the API
+This component is an implementation of `PSR-6`_, which means that its basic API
 is the same as defined in the standard. Before starting to cache information,
 create the cache pool using any of the built-in adapters. For example, to create
 a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::

components/cache/cache_invalidation.rst

@@ -0,0 +1,107 @@
+.. index::
+   single: Cache; Invalidation
+   single: Cache; Tags
+   single: Cache; Namespaces
+
+Cache Invalidation
+==================
+
+Cache invalidation is the process of removing all cached items related to a
+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 three mechanisms to help solve this problem:
+
+* Tags based invalidation for managing data dependencies;
+* Namespace based invalidation for context and sub-contexts dependend data;
+* Expiration based invalidation for time related dependencies.
+
+.. versionadded:: 3.2
+    Tags and namespace based invalidation was introduced in Symfony 3.2.
+
+Using Cache Tags
+----------------
+
+To benefit from the tags based invalidation, your responsiblity is to attach the
+proper tags to each cached items. Each tag is a plain string identifier that you
+can use to trigger the removal of all items that had this tag attached to them.
+
+To attach tags to cached items, you need to use the
+:method:`Symfony\\Component\\Cache\\CacheItem::tag` method that is implemented by
+cache items, as returned by cache adapters::
+
+    $item = $cache->getItem('cache_key');
+    // ...
+    // add one or more tags
+    $item->tag('tag_1');
+    $item->tag(array('tag_2', 'tag_3'));
+    $cache->save($item);
+
+If `$cache` implements :class:`Symfony\\Component\\Cache\\TagAwareAdapterInterface`,
+you can invalidate the cached items by calling
+:method:`Symfony\\Component\\Cache\\TagAwareAdapterInterface::invalidateTags`::
+
+    // invalidate all items related to `tag_1`
+    $cache->invalidateTags('tag_2');
+
+    // or invalidate all items related to `tag_1` or `tag_3`
+    $cache->invalidateTags(array('tag_1', 'tag_3'));
+
+Of course when you know the cache key, it's better to call
+``$cache->deleteItem('cache_key');``, but this key is sometimes hard to track
+and this is where cache tags become useful.
+
+Tag Aware Adapters
+~~~~~~~~~~~~~~~~~~
+
+To store tags, you need to wrap a cache adapter with the
+:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class or implement
+:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface` and its only
+:method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`
+method by yourself.
+
+The :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class implements
+instantaneous invalidation. It needs one or two cache adapters: the required one
+is used to store cached items; the second one is used to store tags and their
+invalidation version number (conceptually similar to their latest invalidation
+date). When only one adapter is used, items and tags are all stored in the same
+place. By using two adapters, you can e.g. store some big cached items on the
+filesystem or in the database, and keep tags in a Redis database to sync all your
+fronts and have very fast invalidation checks::
+
+    $cache = new TagAwareAdapter(
+        // Adapter for cached items
+        new FilesystemAdapter(),
+        // Adapter for tags
+        new RedisAdapter('redis://localhost')
+    );
+
+Using Cache Namespaces
+----------------------
+
+By using adapters that implement the
+:method:`Symfony\\Component\\Cache\\Adapter\\ForkableAdapterInterface::fork`
+method from :class:`Symfony\\Component\\Cache\\Adapter\\ForkableAdapterInterface`,
+you can create context-dependent variations of your cached items::
+
+    $childCache = $parentCache->fork('child-namespace-name');
+    $siblingCache = $parentCache->fork('sibling-namespace-name');
+    $subChildCache = $childCache->fork('sub-child-namespace-name');
+
+Clearing a parent adapter also clears all its forks::
+
+    $childCache->clear();
+    // both $childCache and $subChildCache are now empty
+    // but $parentCache and $siblingCache weren't affected
+
+.. note::
+
+    Invalidating by tags affects all forks.
+
+Using Cache Expiration
+----------------------
+
+If your data is valid only for a limited period of time, you can specify their
+lifetime or their expiration date with the PSR-6 interface, as explained in the
+Cache Items article.

components/cache/cache_items.rst

@@ -13,7 +13,7 @@ In the Cache component they are represented by the
 Cache Item Keys and Values
 --------------------------
 
-The **key** of a cache item is a UTF-8 encoded string which acts as its
+The **key** of a cache item is a plain string which acts as its
 identifier, so it must be unique for each cache pool. You can freely choose the
 keys, but they should only contain letters (A-Z, a-z), numbers (0-9) and the
 ``_`` and ``.`` symbols. Other common symbols (such as ``{``, ``}``, ``(``,

components/cache/cache_pools.rst

@@ -41,7 +41,7 @@ Filesystem Cache Adapter
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 This adapter is useful when you want to improve the application performance but
-can't install tools like APC or Redis in the server. This adapter stores the
+can't install tools like APCu or Redis in the server. This adapter stores the
 contents as regular files in a set of directories on the local file system::
 
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
@@ -83,7 +83,7 @@ degrade performance significantly::
 Redis Cache Adapter
 ~~~~~~~~~~~~~~~~~~~
 
-This adapter stores the contents in the memory of the server. Unlike the APCu
+This adapter stores the contents in the memory of a Redis server. Unlike the APCu
 adapter, it's not limited to the shared memory of the current server, so you can
 store contents in a cluster of servers if needed.
 
@@ -102,6 +102,33 @@ the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes::
         $defaultLifetime = 0
     );
 
+The :method:`Symfony\\Component\\Cache\\Adapter\\RedisAdapter::createConnection`
+helper allows creating a connection to a Redis server using a DSN configuration::
+
+    $redisConnection = RedisAdapter::createConnection('redis://localhost');
+
+See the method's docblock for more options.
+
+PDO & Doctrine DBAL Cache Adapter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This adapter stores the cached items a SQL database accessed through a PDO or a
+Doctrine DBAL connection::
+
+    use Symfony\Component\Cache\Adapter\PdoAdapter;
+
+    $cache = new PdoAdapter(
+        // a PDO, a Doctrine DBAL connection or DSN for lazy connecting through PDO
+        $databaseConnectionOrDSN,
+        // the string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+        // in seconds; applied to cache items that don't define their own lifetime
+        // 0 means to store the cache items indefinitely (i.e. until the Redis memory is deleted)
+        $defaultLifetime = 0,
+        // an array of options for configuring the database connection
+        $options = array()
+    );
+
 Chain Cache Adapter
 ~~~~~~~~~~~~~~~~~~~
 
@@ -141,9 +168,6 @@ that external cache and save them in the Symfony cache of your application::
 The adapter accepts two additional optional arguments: the namespace (``''`` by
 default) and the default lifetime (``0`` by default).
 
-Another use case for this adapter is to get statistics and metrics about the
-cache hits (``getHits()``) and misses (``getMisses()``).
-
 Doctrine Cache Adapter
 ~~~~~~~~~~~~~~~~~~~~~~