cleanup all cache adapter documentation, extend redis docs

Author: robfrawley

components/cache.rst

@@ -3,6 +3,8 @@
    single: Performance
    single: Components; Cache
 
+.. _`cache-component`:
+
 The Cache Component
 ===================
 

components/cache/adapters/apcu_adapter.rst

@@ -2,25 +2,53 @@
     single: Cache Pool
     single: APC Cache, APCu Cache
 
+.. _apcu-adapter:
+
 APCu Cache Adapter
 ==================
 
-This adapter can increase the application performance very significantly,
-because contents are cached in the shared memory of your server, which is much
-faster than the file system. It requires to have installed and enabled the PHP
-APCu extension. It's not recommended to use it when performing lots of write and
-delete operations because it produces fragmentation in the APCu memory that can
-degrade performance significantly::
+This adapter is a high-performance, shared memory cache. It can increase the
+application performance very significantly because the cache contents are
+stored in the shared memory of your server, a component that is much faster than
+others, such as the file system.
+
+.. caution::
+
+    **Requirement:** The `APCu extension`_ must be installed and active to use
+    this adapter.
+
+This adapter can be provided an optional namespace string as its first parameter, a
+default cache lifetime as its second parameter, and a version string as its third
+parameter::
 
     use Symfony\Component\Cache\Adapter\ApcuAdapter;
 
     $cache = new ApcuAdapter(
-        // the string prefixed to the keys of the items stored in this cache
+
+        // a 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 APC memory is deleted)
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the APCu memory is cleared)
         $defaultLifetime = 0,
-        // if present, this string is added to the namespace to simplify the
-        // invalidation of the entire cache (e.g. when deploying the application)
+
+        // when set, all keys prefixed by $namespace can be invalidated by changing
+        // this $version string
         $version = null
     );
+
+.. caution::
+
+    It is *not* recommended to use this adapter when performing a large number of
+    write and delete operations, as these operations result in fragmentation of the
+    APCu memory, resulting in *significantly* degraded performance.
+
+.. tip::
+
+    Note that this adapters CRUD operations are specific to the PHP SAPI it is running
+    under. This means adding a cache item using the CLI will not result in the item
+    appearing under FPM. Likewise, deletion of an item using CGI will not result in the
+    item being deleted under the CLI.
+
+.. _`APCu extension`: https://pecl.php.net/package/APCu

components/cache/adapters/array_cache_adapter.rst

@@ -5,16 +5,23 @@
 Array Cache Adapter
 ===================
 
-This adapter is only useful for testing purposes because contents are stored in
-memory and not persisted in any way. Besides, some features explained later are
-not available, such as the deferred saves::
+Generally, this adapter is useful for testing purposes, as its contents are stored in memory
+and not persisted outside the running PHP process in any way. It can also be useful while
+warming up caches, due to the :method:`Symfony\\Component\\Cache\\Adapter\\ArrayAdapter::getValues`
+method.
+
+This adapter can be passed a default cache lifetime as its first parameter, and a boolean that
+toggles serialization as its second parameter::
 
     use Symfony\Component\Cache\Adapter\ArrayAdapter;
 
     $cache = new ArrayAdapter(
-        // 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 current PHP process finishes)
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the current PHP process finishes)
         $defaultLifetime = 0,
+
         // if ``true``, the values saved in the cache are serialized before storing them
         $storeSerialized = true
     );

components/cache/adapters/chain_adapter.rst

@@ -5,22 +5,39 @@
 Chain Cache Adapter
 ===================
 
-This adapter allows to combine any number of the previous adapters. Cache items
-are fetched from the first adapter which contains them. Besides, cache items are
-saved in all the given adapters, so this is a simple way of creating a cache
-replication::
+This adapter allows to combine any number of the other available cache adapters.
+Cache items are fetched from the first adapter which contains them and cache items are
+saved in all the given adapters. This offers a simple way of creating a layered cache.
+
+This adapter expects an array of adapters as its first parameter, and optionally a
+maximum cache lifetime as its second parameter::
 
     use Symfony\Component\Cache\Adapter\ApcuAdapter;
-    use Symfony\Component\Cache\Adapter\ChainAdapter;
-    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
-    $apcCache = new ApcuAdapter();
-    $fileCache = new FilesystemAdapter();
+    $cache = new ChainAdapter(array(
+
+        // The ordered list of adapters used to fetch cached items
+        array $adapters,
+
+        // The max lifetime of items propagated from lower adapters to upper ones
+        $maxLifetime = 0
+    ));
+
+.. note::
 
-    $cache = new ChainAdapter(array($apcCache, $fileCache));
+    When an item is not found in the first adapters but is found in the next ones, this
+    adapter ensures that the fetched item is saved in all the adapters where it was
+    previously missing.
+
+The following shows how to create a chain adapter instance using the fastest and slowest
+storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter` and
+:class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`, respectfully::
+
+    use Symfony\Component\Cache\Adapter\ApcuAdapter;
+    use Symfony\Component\Cache\Adapter\ChainAdapter;
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
-When an item is not found in the first adapters but is found in the next ones,
-the ``ChainAdapter`` ensures that the fetched item is saved in all the adapters
-where it was missing. Since it's not possible to know the expiry date and time
-of a cache item, the second optional argument of ``ChainAdapter`` is the default
-lifetime applied to those cache items (by default it's ``0``).
+    $cache = new ChainAdapter(array(
+        new ApcuAdapter(),
+        new FilesystemAdapter(),
+    ));

components/cache/adapters/doctrine_adapter.rst

@@ -2,21 +2,36 @@
     single: Cache Pool
     single: Doctrine Cache
 
+.. _`doctrine-adapter`:
+
 Doctrine Cache Adapter
 ======================
 
-This adapter wraps any `Doctrine Cache`_ provider so you can use them in your
-application as if they were Symfony Cache adapters::
+This adapter wraps any class extending the `Doctrine Cache`_ abstract provider, allowing
+you to use these providers in your application as if they were Symfony Cache adapters.
+
+This adapter expects a ``\Doctrine\Common\Cache\CacheProvider`` instance as its first
+parameter, and optionally a namespace and default cache lifetime as its second and
+third parameters::
 
+    use Doctrine\Common\Cache\CacheProvider;
     use Doctrine\Common\Cache\SQLite3Cache;
     use Symfony\Component\Cache\Adapter\DoctrineAdapter;
 
-    $sqliteDatabase = new \SQLite3(__DIR__.'/cache/data.sqlite');
-    $doctrineCache = new SQLite3Cache($sqliteDatabase, 'tableName');
-    $symfonyCache = new DoctrineAdapter($doctrineCache);
+    $provider = new SQLite3Cache(new \SQLite3(__DIR__.'/cache/data.sqlite'), 'youTableName');
+
+    $symfonyCache = new DoctrineAdapter(
+
+        // a cache provider instance
+        CacheProvider $provider,
+
+        // a string prefixed to the keys of the items stored in this cache
+        $namespace = '',
 
-This adapter also defines two optional arguments called  ``namespace`` (default:
-``''``) and ``defaultLifetime`` (default: ``0``) and adapts them to make them
-work in the underlying Doctrine cache.
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the database table is truncated or its rows are otherwise deleted)
+        $defaultLifetime = 0
+    );
 
 .. _`Doctrine Cache`: https://github.com/doctrine/cache

components/cache/adapters/filesystem_adapter.rst

@@ -6,18 +6,33 @@ Filesystem Cache Adapter
 ========================
 
 This adapter is useful when you want to improve the application performance but
-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::
+can't install tools like APCu or Redis on the server. This adapter stores the
+contents as regular files in a set of directories on the local file system.
+
+This adapter can optionally be provided a namespace, default cache lifetime, and
+directory path, as its first, second, and third parameters::
 
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
     $cache = new FilesystemAdapter(
-        // the subdirectory of the main cache directory where cache items are stored
+
+        // a string used as the subdirectory of the root cache directory, where cache
+        // items will be stored
         $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 files are deleted)
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the files are deleted)
         $defaultLifetime = 0,
+
         // the main cache directory (the application needs read-write permissions on it)
         // if none is specified, a directory is created inside the system temporary directory
         $directory = null
     );
+
+.. tip::
+
+    This adapter is generally the *slowest* due to the overhead of file IO. If throughput is paramount,
+    the in-memory adapters (such as :ref:`APCu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`,
+    and :ref:`Redis <redis-adapter>`) or the database adapters (such as
+    :ref:`Doctrine <doctrine-adapter>` and :ref:`PDO & Doctrine <pdo-doctrine-adapter>`) are recommended.

components/cache/adapters/memcached_adapter.rst

@@ -2,6 +2,8 @@
     single: Cache Pool
     single: Memcached Cache
 
+.. _memcached-adapter:
+
 Memcached Cache Adapter
 =======================
 
@@ -10,15 +12,17 @@ Memcached Cache Adapter
     The Memcached adapter was introduced in Symfony 3.3.
 
 This adapter stores the values in-memory using one (or more) `Memcached server`_
-instances. Unlike the ACPu adapter, and similarly to the Redis adapter, it is
-not limited to the current server's shared memory; you can store contents
-independent of your PHP environment. The ability to utilize a cluster of servers
-to provide redundancy and/or fail-over is also available.
+instances. Unlike the :ref:`APCu adapter <apcu-adapter>`, and similarly to the
+:ref:`Redis adapter <redis-adapter>`, it is not limited to the current server's
+shared memory; you can store contents independent of your PHP environment.
+The ability to utilize a cluster of servers to provide redundancy and/or fail-over
+is also available.
 
 .. caution::
 
-    The `Memcached PHP extension`_ as well as a `Memcached server`_ must be
-    installed, active, and running to use this adapter.
+    **Requirements:** The `Memcached PHP extension`_ as well as a `Memcached server`_
+    must be installed, active, and running to use this adapter. Version ``2.2`` or
+    greater of the `Memcached PHP extension`_ is required for this adapter.
 
 This adapter expects a `Memcached`_ instance to be passed as the first
 parameter. A namespace and default cache lifetime can optionally be passed as
@@ -71,7 +75,7 @@ The DSN must include a IP/host (and an optional port) or a socket path, an
 optional username and password (for SASL authentication; it requires that the
 memcached extension was compiled with ``--enable-memcached-sasl``) and an
 optional weight (for prioritizing servers in a cluster; its value is an integer
-between ``0`` and ``100`` which defaults to ``XX``; a higher value means more
+between ``0`` and ``100`` which defaults to ``null``; a higher value means more
 priority).
 
 Below are common examples of valid DSNs showing a combination of available values::
@@ -201,7 +205,7 @@ Available Options
     expense of more write traffic.
 
 ``recv_timeout`` (type: ``int``, default: ``0``)
-    Specifies he amount of time (in microseconds) before timing out during an outgoing socket (read) operation.
+    Specifies the amount of time (in microseconds) before timing out during an outgoing socket (read) operation.
     When the ``no_block`` option isn't enabled, this will allow you to still have timeouts on the reading of data.
 
     Valid option values include ``0`` or *any positive integer*.
@@ -275,7 +279,7 @@ Available Options
     are valid and fit within the design of the protocol being used.
 
 .. tip::
-    Reference the `Memcached extension`_'s `predefined constants`_ documentation
+    Reference the `Memcached`_ extension's `predefined constants`_ documentation
     for additional information about the available options.
 
 .. _`Transmission Control Protocol (TCP)`: https://en.wikipedia.org/wiki/Transmission_Control_Protocol

components/cache/adapters/pdo_doctrine_dbal_adapter.rst

@@ -2,6 +2,8 @@
     single: Cache Pool
     single: PDO Cache, Doctrine DBAL Cache
 
+.. _`pdo-doctrine-adapter`:
+
 PDO & Doctrine DBAL Cache Adapter
 =================================
 
@@ -10,19 +12,35 @@ PDO & Doctrine DBAL Cache Adapter
    The PDO & Doctrine DBAL adapter was introduced in Symfony 3.2.
 
 
-This adapter stores the cached items a SQL database accessed through a PDO or a
-Doctrine DBAL connection::
+This adapter stores the cache items in an SQL database. It requires a `PDO`_,
+`Doctrine DBAL Connection`_, or `Data Source Name (DSN)`_ as its first parameter, and
+optionally a namespace, default cache lifetime, and options array as its second,
+third, and forth parameters::
 
     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 database is cleared)
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the database table is truncated or its rows are otherwise deleted)
         $defaultLifetime = 0,
+
         // an array of options for configuring the database connection
         $options = array()
     );
+
+.. tip::
+
+    When passed a `Data Source Name (DSN)`_ string (instead of a database connection
+    class instance), the connection will be lazy-loaded when needed.
+
+.. _`PDO`: http://php.net/manual/en/class.pdo.php
+.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
+.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

components/cache/adapters/proxy_adapter.rst

@@ -5,15 +5,32 @@
 Proxy Cache Adapter
 ===================
 
-This adapter is useful to integrate in your application cache pools not created
-with the Symfony Cache component. As long as those cache pools implement the
-``CacheItemPoolInterface`` interface, this adapter allows you to get items from
-that external cache and save them in the Symfony cache of your application::
+This adapter wraps a `PSR-6`_ compliant `cache item pool interface`_. It is used to integrate
+your application's cache item pool implementation with the Symfony :ref:`Cache Component <cache-component>`
+by consuming any implementation of ``Psr\Cache\CacheItemPoolInterface``.
 
+This adapter expects a ``Psr\Cache\CacheItemPoolInterface`` instance as its first parameter,
+and optionally a namespace and default cache lifetime as its second and third parameters::
+
+    use Psr\Cache\CacheItemPoolInterface;
     use Symfony\Component\Cache\Adapter\ProxyAdapter;
 
-    // ... create $nonSymfonyCache somehow
-    $cache = new ProxyAdapter($nonSymfonyCache);
+    $psr6CachePool = \\ create your own cache pool instance that implements the PSR-6
+                     \\ interface `CacheItemPoolInterface`
+
+    $cache = new ProxyAdapter(
+
+        // a cache pool instance
+        CacheItemPoolInterface $psr6CachePool,
+
+        // a string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until the cache is cleared)
+        $defaultLifetime = 0
+    );
 
-The adapter accepts two additional optional arguments: the namespace (``''`` by
-default) and the default lifetime (``0`` by default).
+.. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
+.. _`cache item pool interface`: http://www.php-fig.org/psr/psr-6/#cacheitempoolinterface