refactor cache pool documentation and add memcached adapter docs

Author: robfrawley

components/cache/adapters/apcu_adapter.rst

@@ -0,0 +1,26 @@
+.. index::
+    single: Cache Pool
+    single: APC Cache, APCu Cache
+
+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::
+
+    use Symfony\Component\Cache\Adapter\ApcuAdapter;
+
+    $cache = new ApcuAdapter(
+        // 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 APC memory is deleted)
+        $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)
+        $version = null
+    );

components/cache/adapters/array_cache_adapter.rst

@@ -0,0 +1,20 @@
+.. index::
+    single: Cache Pool
+    single: Array Cache
+
+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::
+
+    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)
+        $defaultLifetime = 0,
+        // if ``true``, the values saved in the cache are serialized before storing them
+        $storeSerialized = true
+    );

components/cache/adapters/chain_adapter.rst

@@ -0,0 +1,26 @@
+.. index::
+    single: Cache Pool
+    single: Chain Cache
+
+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::
+
+    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($apcCache, $fileCache));
+
+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``).

components/cache/adapters/doctrine_adapter.rst

@@ -0,0 +1,22 @@
+.. index::
+    single: Cache Pool
+    single: Doctrine Cache
+
+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::
+
+    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);
+
+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.
+
+.. _`Doctrine Cache`: https://github.com/doctrine/cache

components/cache/adapters/filesystem_adapter.rst

@@ -0,0 +1,23 @@
+.. index::
+    single: Cache Pool
+    single: Filesystem Cache
+
+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::
+
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+    $cache = new FilesystemAdapter(
+        // the subdirectory of the main cache directory where cache items are 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)
+        $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
+    );