feature #7265 [Cache] Memcached Adapter Docs and Cache Pool Docs Refactoring (robfrawley, javiereguiluz)

This PR was merged into the master branch.

Discussion
----------

[Cache] Memcached Adapter Docs and Cache Pool Docs Refactoring

Documentation for symfony/symfony#20863 and symfony/symfony#20858. PR symfony/symfony#20863 is still being written/finalized, so this is a WIP following that PR at this time. Resolves #7256.

Commits
-------

7db929c corrected spelling/grammar
c49d427 cleanup all cache adapter documentation, extend redis docs
e3eff5b Reviewed the entire article
d4292b7 refactor cache pool documentation and add memcached adapter docs

Author: xabbuh

components/cache.rst

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

components/cache/adapters/apcu_adapter.rst

@@ -0,0 +1,54 @@
+.. index::
+    single: Cache Pool
+    single: APC Cache, APCu Cache
+
+.. _apcu-adapter:
+
+APCu Cache Adapter
+==================
+
+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 filesystem.
+
+.. 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(
+
+        // 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 APCu memory is cleared)
+        $defaultLifetime = 0,
+
+        // 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 adapter's 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

@@ -0,0 +1,27 @@
+.. index::
+    single: Cache Pool
+    single: Array Cache
+
+Array Cache Adapter
+===================
+
+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(
+
+        // 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

@@ -0,0 +1,43 @@
+.. index::
+    single: Cache Pool
+    single: Chain Cache
+
+Chain Cache Adapter
+===================
+
+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;
+
+    $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::
+
+    When an item is not found in the first adapter 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 example 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;
+
+    $cache = new ChainAdapter(array(
+        new ApcuAdapter(),
+        new FilesystemAdapter(),
+    ));

components/cache/adapters/doctrine_adapter.rst

@@ -0,0 +1,37 @@
+.. index::
+    single: Cache Pool
+    single: Doctrine Cache
+
+.. _`doctrine-adapter`:
+
+Doctrine Cache Adapter
+======================
+
+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;
+
+    $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 = '',
+
+        // 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

@@ -0,0 +1,38 @@
+.. 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 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(
+
+        // a string used as the subdirectory of the root cache directory, where cache
+        // items will be stored
+        $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 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.