[Cache] Memcached Adapter Docs and Cache Pool Docs Refactoring

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 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(
+
+ // 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 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

@@ -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 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;
+
+ $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.