refactor cache pool documentation and add memcached adapter docs

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
+ );