feature #7417 Adding documentation about the simple cache PSR-16 implementation (weaverryan)

This PR was squashed before being merged into the master branch (closes #7417).

Discussion
----------

Adding documentation about the simple cache PSR-16 implementation

Hi guys!

This covers #7409!

Cheers!

Commits
-------

a6daf92 Adding documentation about the simple cache PSR-16 implementation

Author: weaverryan

components/cache.rst

@@ -6,13 +6,17 @@
 The Cache Component
 ===================
 
-    The Cache component provides an extended `PSR-6`_ implementation for adding
-    cache to your applications. It is designed to have a low overhead and it
-    ships with ready to use adapters for the most common caching backends.
+    The Cache component provides an extended `PSR-6`_ implementation as well as
+    a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications.
+    It is designed to have a low overhead and it ships with ready to use adapters
+    for the most common caching backends.
 
 .. versionadded:: 3.1
     The Cache component was introduced in Symfony 3.1.
 
+.. versionadded:: 3.3
+    The PSR-16 "Simple Cache" implementation was introduced in Symfony 3.3.
+
 Installation
 ------------
 
@@ -21,11 +25,113 @@ You can install the component in 2 different ways:
 * :doc:`Install it via Composer </components/using_components>` (``symfony/cache`` on `Packagist`_);
 * Use the official Git repository (https://github.com/symfony/cache).
 
-Key Concepts
-------------
+Cache (PSR-6) Versus Simple Cache (PSR-16)
+------------------------------------------
+
+This component includes *two* different approaches to caching:
+
+:ref:`PSR-6 Caching <cache-component-psr6-caching>`:
+     A fully-featured cache system, which includes cache "pools", more advanced
+     cache "items", and :ref:`cache tagging for invalidation <cache-component-tags>`.
+
+:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
+    A simple way to store, fetch and remove items from a cache.
+
+Both methods support the *same* cache adapters and will give you very similar performance.
+
+.. tip::
+
+    The component also contains adapters to convert between PSR-6 and PSR-16 caches.
+    See :doc:`/components/cache/psr6_psr16_adapters`.
+
+.. _cache-component-psr16-caching:
+
+Simple Caching (PSR-16)
+-----------------------
+
+This part of the component is an implementation of `PSR-16`_, which means that its
+basic API is the same as defined in the standard. First, create a cache object from
+one of the built-in cache classes. For example, to create a filesystem-based cache,
+instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
+
+    use Symfony\Component\Cache\Simple\FilesystemCache;
+
+    $cache = new FilesystemCache();
+
+Now you can create, retrieve, update and delete items using this object::
+
+    // save a new item in the cache
+    $cache->set('stats.num_products', 4711);
+
+    // or set it with a custom ttl
+    // $cache->set('stats.num_products', 4711, 3600);
+
+    // retrieve the cache item
+    if (!$cache->has('stats.num_products')) {
+        // ... item does not exists in the cache
+    }
+
+    // retrieve the value stored by the item
+    $numProducts = $cache->get('stats.num_products');
+
+    // or specify a default value, if the key doesn't exist
+    // $numProducts = $cache->get('stats.num_products', 100);
+
+    // remove the cache key
+    $cache->delete('stats.num_products');
+    
+    // clear *all* cache keys
+    $cache->clear();
+
+You can also work with multiple items at once::
+
+    $cache->setMultiple(array(
+        'stats.num_products' => 4711,
+        'stats.num_users' => 1356,
+    ));
+
+    $stats = $cache->getMultiple(array(
+        'stats.num_products',
+        'stats.num_users',
+    ));
 
-Before starting to use the Cache component, it's important that you learn the
-meaning of some key concepts:
+    $cache->deleteMultiple(array(
+        'stats.num_products',
+        'stats.num_users',
+    ));
+
+Available Simple Cache (PSR-16) Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following cache adapters are available:
+
+.. tip::
+
+    To find out more about each of these classes, you can read the
+    :doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
+    (PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
+    each share constructor arguments and use-cases.
+
+* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
+* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
+
+.. _cache-component-psr6-caching:
+
+More Advanced Caching (PSR-6)
+-----------------------------
+
+To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
+concepts:
 
 **Item**
     A single unit of information stored as a key/value pair, where the key is
@@ -39,11 +145,11 @@ meaning of some key concepts:
     filesystem, in a database, etc. The component provides several ready to use
     adapters for common caching backends (Redis, APCu, etc.)
 
-Basic Usage
------------
+Basic Usage (PSR-6)
+-------------------
 
-This component is an implementation of `PSR-6`_, which means that its basic API
-is the same as defined in the standard. Before starting to cache information,
+This part of the component is an implementation of `PSR-6`_, which means that its
+basic API is the same as defined in the standard. Before starting to cache information,
 create the cache pool using any of the built-in adapters. For example, to create
 a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::
 
@@ -71,8 +177,10 @@ Now you can create, retrieve, update and delete items using this cache pool::
     // remove the cache item
     $cache->deleteItem('stats.num_products');
 
-Advanced Usage
---------------
+For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
+
+Advanced Usage (PSR-6)
+----------------------
 
 .. toctree::
     :glob:
@@ -81,4 +189,5 @@ Advanced Usage
     cache/*
 
 .. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
+.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
 .. _Packagist: https://packagist.org/packages/symfony/cache

components/cache/cache_pools.rst

@@ -5,8 +5,8 @@
    single: Redis Cache
    single: PDO Cache, Doctrine DBAL Cache
 
-Cache Pools
-===========
+Cache Pools and Supported Adapters
+==================================
 
 Cache Pools are the logical repositories of cache items. They perform all the
 common operations on items, such as saving them or looking for them. Cache pools
@@ -107,8 +107,9 @@ This adapter stores the contents in the memory of a Redis server. Unlike the APC
 adapter, it's not limited to the shared memory of the current server, so you can
 store contents in a cluster of servers if needed.
 
-It requires to have installed Redis and have created a connection that implements
-the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes::
+Before you start, make sure you have Redis running and have created a connection
+that implements the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis``
+classes::
 
     use Symfony\Component\Cache\Adapter\RedisAdapter;
 
@@ -127,6 +128,48 @@ helper allows creating a connection to a Redis server using a DSN configuration:
 
     $redisConnection = RedisAdapter::createConnection('redis://localhost');
 
+    $cache = new RedisAdapter($redisConnection);
+
+See the method's docblock for more options.
+
+Memcached Cache Adapter
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This adapter stores the contents into a set of `Memcached`_ servers.
+
+Before you start, make sure you have Memcached running and have created a
+:phpclass:`Memcached` object::
+
+    use Symfony\Component\Cache\Adapter\MemcachedAdapter;
+
+    $cache = new MemcachedAdapter(
+        // the object that stores a valid connection to your Memcached servers
+        \Memcached $client,
+        // 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 Memcached memory is deleted)
+        $defaultLifetime = 0
+    );
+
+The :method:`Symfony\\Component\\Cache\\Adapter\\Memcached::createConnection`
+helper allows creating a connection to a pool of Memcached server using a DSN configuration::
+
+    $memcachedClient = MemcachedAdapter::createConnection(
+        'memcached://user:pass@localhost?weight=33',
+
+        // options, including username, password and Memcached::OPT_* options
+        array('persistent_id' => '_products_cache')
+    );
+
+    // alternate syntax: array notations for the servers
+    $memcachedClient = MemcachedAdapter::createConnection(array(
+        array('192.168.1.100', 11211, 33),
+        array('192.168.1.101', 11211, 33)
+    ));
+
+    $cache = new MemcachedAdapter($memcachedClient);
+
 See the method's docblock for more options.
 
 PDO & Doctrine DBAL Cache Adapter
@@ -175,6 +218,25 @@ 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``).
 
+Traceable Adapter
+~~~~~~~~~~~~~~~~~
+
+This adapter wraps another adapter, and allows you to read a report of all of the
+"calls" made to the adapter, including how long actions took, cache hits, misses
+and more::
+
+    use Symfony\Component\Cache\Adapter\TraceableAdapter;
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+    $fileCache = new FilesystemAdapter();
+
+    $cache = new TraceableAdapter($fileCache);
+    
+    // work with the $cache adapter like normal
+
+    // returns an array of TraceableAdapterEvent describing the calls
+    $events = $cache->getCalls();
+
 Proxy Cache Adapter
 ~~~~~~~~~~~~~~~~~~~
 
@@ -333,3 +395,4 @@ when all items are successfully deleted)::
     $cacheIsEmpty = $cache->clear();
 
 .. _`Doctrine Cache`: https://github.com/doctrine/cache
+.. _`Memcached`: http://php.net/manual/en/book.memcached.php

components/cache/psr6_psr16_adapters.rst

@@ -0,0 +1,86 @@
+.. index::
+   single: Cache
+   single: Performance
+   single: Components; Cache
+
+Adapters For Interoperability between PSR-6 and PSR-16 Cache
+============================================================
+
+Sometimes, you may have a Cache object that implements the :ref:`PSR-16 <cache-component-psr16-caching>`
+standard, but need to pass it to an object that expects a :ref:`PSR-6 <cache-component-psr6-caching>`
+cache adapter. Or, you might have the opposite situation. The cache component contains
+two classes for bidirectional interoperability between PSR-6 and PSR-16 caches.
+
+Using a PSR-16 Cache Object as a PSR-6 Cache
+--------------------------------------------
+
+Suppose you want to work with a class that requires a PSR-6 Cache pool object. For
+example::
+
+    use Psr\Cache\CacheItemPoolInterface;
+
+    // just a made-up class for the example
+    class GitHubApiClient
+    {
+        // ...
+
+        // this requires a PSR-6 cache object
+        public function __construct(CacheItemPoolInterface $cachePool)
+        {
+            // ...
+        }
+    }
+
+But, you already have a PSR-16 cache object, and you'd like to pass this to the class
+instead. No problem! The Cache component provides the
+:class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter` class for exactly
+this use-case::
+
+    use Symfony\Component\Cache\Simple\FilesystemCache;
+    use Symfony\Component\Cache\Adapter\SimpleCacheAdapter
+
+    // the PSR-16 cache object that you want to use
+    $psr16Cache = new FilesystemCache();
+
+    // a PSR-6 cache that uses your cache internally!
+    $psr6Cache = new SimpleCacheAdapter($psr16Cache);
+    
+    // now use this wherever you want
+    $githubApiClient = new GitHubApiClient($psr6Cache);
+
+Using a PSR-6 Cache Object as a PSR-16 Cache
+--------------------------------------------
+
+Suppose you want to work with a class that requires a PSR-16 Cache object. For
+example::
+
+    use Psr\SimpleCache\CacheInterface;
+
+    // just a made-up class for the example
+    class GitHubApiClient
+    {
+        // ...
+
+        // this requires a PSR-16 cache object
+        public function __construct(CacheInterface $cache)
+        {
+            // ...
+        }
+    }
+
+But, you already have a PSR-6 cache pool object, and you'd like to pass this to
+the class instead. No problem! The Cache component provides the
+:class:`Symfony\\Component\\Cache\\Simple\\Psr6Cache` class for exactly
+this use-case::
+
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+    use Symfony\Component\Cache\Simple\Psr6Cache;
+
+    // the PSR-6 cache object that you want to use
+    $psr6Cache = new FilesystemAdapter();
+
+    // a PSR-16 cache that uses your cache internally!
+    $psr16Cache = new Psr6Cache($psr6Cache);
+    
+    // now use this wherever you want
+    $githubApiClient = new GitHubApiClient($psr16Cache);