Merge branch '4.2'

* 4.2:
  Update Cache component doc for 4.2

Author: javiereguiluz

components/cache.rst

@@ -8,11 +8,12 @@
 The Cache Component
 ===================
 
-    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 for performance and resiliency, and ships with ready to use
-    adapters for the most common caching backends, including proxies for adapting
-    from/to `Doctrine Cache`_.
+    The Cache component provides features covering simple to advanced caching needs.
+    It natively implements `PSR-6`_ and the `Cache Contract`_ for greatest
+    interoperability. It is designed for performance and resiliency, ships with
+    ready to use adapters for the most common caching backends, including proxies for
+    adapting from/to `Doctrine Cache`_ and `PSR-16`_. It enables tag-based invalidation
+    and cache stampede protection.
 
 Installation
 ------------
@@ -23,112 +24,133 @@ Installation
 
 .. include:: /components/require_autoload.rst.inc
 
-Cache (PSR-6) Versus Simple Cache (PSR-16)
-------------------------------------------
+.. _cache-psr-6-versus-simple-cache-psr-16:
+
+Cache Contracts versus PSR-6
+----------------------------
 
 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>`.
+     A generic cache system, which involves cache "pools" and cache "items".
+
+:ref:`Cache Contracts <cache-component-contracts>`:
+    A simple yet powerful way to store, fetch and remove values from a cache.
 
-:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
-    A simple way to store, fetch and remove items from a cache.
+.. tip::
 
-Both methods support the *same* cache adapters and will give you very similar performance.
+    Using the Cache Contracts approach is recommended: using it requires less
+    code boilerplate and provides cache stampede protection by default.
 
 .. tip::
 
-    The component also contains adapters to convert between PSR-6 and PSR-16 caches.
-    See :doc:`/components/cache/psr6_psr16_adapters`.
+    The component also contains adapters to convert between PSR-6, PSR-16 and
+    Doctrine caches. See :doc:`/components/cache/psr6_psr16_adapters` and
+    :doc:`/components/cache/adapters/doctrine_adapter`.
 
-.. _cache-component-psr16-caching:
+.. _cache-component-contracts:
 
-Simple Caching (PSR-16)
------------------------
+Cache Contracts
+---------------
 
-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`::
+All adapters supports the Cache Contract. It contains only two methods:
+``get()`` and ``delete()``. There's no ``set()`` method because the ``get()``
+method both gets and sets the cache values.
 
-    use Symfony\Component\Cache\Simple\FilesystemCache;
+The first thing you need is to instantiate a cache adapter. The
+:class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache` is used in this
+example::
 
-    $cache = new FilesystemCache();
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
-Now you can create, retrieve, update and delete items using this object::
+    $cache = new FilesystemAdapter();
 
-    // save a new item in the cache
-    $cache->set('stats.products_count', 4711);
+Now you can retrieve and delete cached data using this object. The first
+argument of the ``get()`` method is a key, an arbitrary string that you
+associate to the cached value so you can retrieve it later. The second argument
+is a PHP callable which is executed to generate the value (and store it in the
+cache) when it's not found in the cache::
 
-    // or set it with a custom ttl
-    // $cache->set('stats.products_count', 4711, 3600);
+    use Symfony\Contracts\Cache\ItemInterface;
 
-    // retrieve the cache item
-    if (!$cache->has('stats.products_count')) {
-        // ... item does not exists in the cache
-    }
+    // The callable will only be executed on a cache miss.
+    $value = $cache->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
 
-    // retrieve the value stored by the item
-    $productsCount = $cache->get('stats.products_count');
+        // ... do some HTTP request or heavy computations
+        $computedValue = 'foobar';
+
+        return $computedValue;
+    });
+
+    echo $value; // 'foobar'
 
-    // or specify a default value, if the key doesn't exist
-    // $productsCount = $cache->get('stats.products_count', 100);
+    // ... and to remove the cache key
+    $cache->delete('my_cache_key');
 
-    // remove the cache key
-    $cache->delete('stats.products_count');
+.. note::
 
-    // clear *all* cache keys
-    $cache->clear();
+    Use cache tags to delete more than one key at the time. Read more at
+    :doc:`/components/cache/cache_invalidation`.
 
-You can also work with multiple items at once::
+The Cache Contracts also comes with built in `Stampede prevention`_. This will
+remove CPU spikes at the moments when the cache is cold. If an example application
+spends 5 seconds to compute data that is cached for 1 hour. This data is accessed
+10 times every second. This means that you mostly have cache hits and everything
+is fine. But after one hour, we get 10 new requests to a cold cache. So the data
+is computed again. The next second the same thing happens. So the data is computed
+about 50 times before the cache is warm again. This is where you need stampede
+prevention
 
-    $cache->setMultiple([
-        'stats.products_count' => 4711,
-        'stats.users_count' => 1356,
-    ]);
+The solution is to recompute the value before the cache expires. The algorithm
+randomly fakes a cache miss for one user while others still is served the cached
+value. You can control its behavior with the third optional parameter of
+``CacheInterface::get()``, which is a float value called "beta".
 
-    $stats = $cache->getMultiple([
-        'stats.products_count',
-        'stats.users_count',
-    ]);
+By default the beta is ``1.0`` and higher values mean earlier recompute. Set it
+to ``0`` to disable the recompute and set it to ``INF`` to trigger an immediate
+recompute::
 
-    $cache->deleteMultiple([
-        'stats.products_count',
-        'stats.users_count',
-    ]);
+    use Symfony\Contracts\Cache\ItemInterface;
 
-Available Simple Cache (PSR-16) Classes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    $beta = 1.0;
+    $value = $cache->get('my_cache_key', function (ItemInterface $item) {
+        $item->expiresAfter(3600);
+        $item->tag(['tag_0', 'tag_1');
+
+        return '...';
+    }, $beta);
+
+Available Cache Adapters
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 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`
+    :doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page.
+
+* :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\ArrayAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\ChainAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\MemcachedAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\NullAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\PhpArrayAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\PhpFilesAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\RedisAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter`
+* :class:`Symfony\\Component\\Cache\\Adapter\\TraceableAdapter`
 
 .. _cache-component-psr6-caching:
 
-More Advanced Caching (PSR-6)
------------------------------
+More Generic Caching (PSR-6)
+----------------------------
 
-To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
+To use the more-generic, PSR-6 Caching abilities, you'll need to learn its key
 concepts:
 
 **Item**
@@ -177,8 +199,10 @@ Now you can create, retrieve, update and delete items using this cache pool::
 
 For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
 
-Advanced Usage (PSR-6)
-----------------------
+.. _advanced-usage-psr-6:
+
+Advanced Usage
+--------------
 
 .. toctree::
     :glob:
@@ -187,5 +211,7 @@ Advanced Usage (PSR-6)
     cache/*
 
 .. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
+.. _`Cache Contract`: https://github.com/symfony/contracts/blob/v1.0.0/Cache/CacheInterface.php
 .. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
 .. _Doctrine Cache: https://www.doctrine-project.org/projects/cache.html
+.. _Stampede prevention: https://en.wikipedia.org/wiki/Cache_stampede

components/cache/psr6_psr16_adapters.rst

@@ -6,7 +6,7 @@
 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>`
+Sometimes, you may have a Cache object that implements the `PSR-16`_
 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.
@@ -84,3 +84,5 @@ this use-case::
 
     // now use this wherever you want
     $githubApiClient = new GitHubApiClient($psr16Cache);
+
+.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/