[Cache] improve doc

Author: nicolas-grekas

components/cache.rst

@@ -9,11 +9,16 @@ The Cache Component
 ===================
 
     The Cache component provides features covering simple to advanced caching needs.
-    It natively implements `PSR-6`_ and the `Cache Contract`_ for greatest
+    It natively implements `PSR-6`_ and the `Cache Contracts`_ 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.
+    ready to use adapters for the most common caching backends. It enables tag-based
+    invalidation and cache stampede protection via locking and early expiration.
+
+.. tip::
+
+    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`.
 
 Installation
 ------------
@@ -33,14 +38,19 @@ This component includes *two* different approaches to caching:
      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.
+    A simpler yet more powerful way to cache values based on recomputation callbacks.
+
+.. tip::
+
+    Using the Cache Contracts approach is recommended: it requires less
+    code boilerplate and provides cache stampede protection by default.
 
 .. _cache-component-contracts:
 
 Cache Contracts
 ---------------
 
-All adapters supports the Cache Contract. It contains only two methods:
+All adapters supports the Cache Contracts. It contains only two methods:
 ``get()`` and ``delete()``. There's no ``set()`` method because the ``get()``
 method both gets and sets the cache values.
 
@@ -55,8 +65,8 @@ example::
 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::
+is a PHP callable which is executed when the key is not found in the cache to
+generate and return the value::
 
     use Symfony\Contracts\Cache\ItemInterface;
 
@@ -82,20 +92,27 @@ cache) when it's not found in the cache::
 
 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
+spends 5 seconds to compute data that is cached for 1 hour and this data is accessed
+10 times every second, this means that you mostly have cache hits and everything
+is fine. But after 1 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
 
-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".
+The first solution that is locking: on a per-host basis, only one PHP process is
+allowed to compute a specific key at a time. Locking is built in by default in so
+that you don't have anything specific to do other than leveraging the Cache
+Contracts.
+
+The second solution is also built in when using the Cache Contracts: instead of
+waiting for the full delay before expiring a value, it is recomputed ahead of its
+expiration date: the `Probabilistic early expiration`_ algorithm randomly fakes a
+cache miss for one user while others still are served the cached value. You can
+control its behavior with the third optional parameter of ``CacheInterface::get()``,
+which is a float value called "beta".
 
 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
+to ``0`` to disable early recompute and set it to ``INF`` to force an immediate
 recompute::
 
     use Symfony\Contracts\Cache\ItemInterface;
@@ -108,52 +125,29 @@ recompute::
         return '...';
     }, $beta);
 
-.. tip::
-
-    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, PSR-16 and
-    Doctrine caches. See :doc:`/components/cache/psr6_psr16_adapters` and
-    :doc:`/components/cache/adapters/doctrine_adapter`.
-
 Available Cache Adapters
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following cache adapters are available:
 
-.. tip::
+.. toctree::
+    :glob:
+    :maxdepth: 1
 
-    To find out more about each of these classes, you can read the
-    :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`
+    adapters/*
 
 .. _cache-component-psr6-caching:
 
-More Generic Caching (PSR-6)
-----------------------------
+Generic Caching (PSR-6)
+-----------------------
 
-To use the more-generic, PSR-6 Caching abilities, you'll need to learn its key
+To use the generic 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
     the unique identifier of the information and the value is its contents;
+    see the :doc:`/components/cache/cache_items` article for more details.
 **Pool**
     A logical repository of cache items. All cache operations (saving items,
     looking for items, etc.) are performed through the pool. Applications can
@@ -167,7 +161,7 @@ Basic Usage (PSR-6)
 -------------------
 
 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,
+basic API is the same as defined in the document. 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`::
 
@@ -207,7 +201,8 @@ Advanced Usage
     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
+.. _`Cache Contracts`: https://github.com/symfony/contracts/blob/master/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
+.. _Probabilistic early expiration: https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration

components/cache/adapters/apcu_adapter.rst

@@ -1,6 +1,6 @@
 .. index::
     single: Cache Pool
-    single: APC Cache, APCu Cache
+    single: APCu Cache
 
 .. _apcu-adapter:
 

components/cache/adapters/doctrine_adapter.rst

@@ -34,4 +34,9 @@ third parameters::
         $defaultLifetime = 0
     );
 
+.. tip::
+
+    A :class:`Symfony\\Component\\Cache\\DoctrineProvider` class is also provided by the
+    component to use any PSR6-compatible implementations with Doctrine-compatible classes.
+
 .. _`Doctrine Cache`: https://github.com/doctrine/cache

components/cache/adapters/php_array_cache_adapter.rst

@@ -6,7 +6,8 @@ Php Array Cache Adapter
 =======================
 
 This adapter is a high performance cache for static data (e.g. application configuration)
-that is optimized and preloaded into OPcache memory storage::
+that is optimized and preloaded into OPcache memory storage. It is suited for any data that
+is mostly read-only after warmup::
 
     use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
     use Symfony\Component\Cache\Adapter\FilesystemAdapter;
@@ -34,5 +35,4 @@ that is optimized and preloaded into OPcache memory storage::
 
 .. note::
 
-    This adapter requires PHP 7.x and should be used with the php.ini setting
-    ``opcache.enable`` on.
+    This adapter requires turning on the ``opcache.enable`` php.ini setting.

components/cache/adapters/php_files_adapter.rst

@@ -29,15 +29,16 @@ file similar to the following::
 
 .. note::
 
+    This adapter requires turning on the ``opcache.enable`` php.ini setting.
     As cache items are included and parsed as native PHP code and due to the way `OPcache`_
     handles file includes, this adapter has the potential to be much faster than other
     filesystem-based caches.
 
 .. caution::
 
-    If you have configured OPcache to
-    :ref:`not check the file timestamps <performance-dont-check-timestamps>`
-    the cached items will not not be invalidated unless you clear OPcache.
+    While it supports updates and because it is using OPcache as a backend, this adapter is
+    better suited for append-mostly needs. Using it other scenarios might lead to periodical
+    reset of the OPcache memory, potentially leading to degreaded performance.
 
 The PhpFilesAdapter can optionally be provided a namespace, default cache lifetime, and cache
 directory path as constructor arguments::

components/cache/adapters/proxy_adapter.rst

@@ -9,6 +9,9 @@ This adapter wraps a `PSR-6`_ compliant `cache item pool interface`_. It is used
 your application's cache item pool implementation with the Symfony :ref:`Cache Component <cache-component>`
 by consuming any implementation of ``Psr\Cache\CacheItemPoolInterface``.
 
+It can also be used to prefix all keys automatically before storing items in the decorated pool,
+effectively allowing the creation of several namespaced pools out of a single one.
+
 This adapter expects a ``Psr\Cache\CacheItemPoolInterface`` instance as its first parameter,
 and optionally a namespace and default cache lifetime as its second and third parameters::
 

components/cache/adapters/redis_adapter.rst

@@ -7,7 +7,7 @@
 Redis Cache Adapter
 ===================
 
-This adapter stores the values in-memory using  one (or more) `Redis server`_ instances.
+This adapter stores the values in-memory using one (or more) `Redis server`_ instances.
 Unlike the :ref:`APCu adapter <apcu-adapter>`, and similarly to the
 :ref:`Memcached adapter <memcached-adapter>`, it is not limited to the current server's
 shared memory; you can store contents independent of your PHP environment. The ability

components/cache/cache_invalidation.rst

@@ -13,7 +13,7 @@ several cached items, keeping them in sync can be difficult.
 The Symfony Cache component provides two mechanisms to help solving this problem:
 
 * :ref:`Tags-based invalidation <cache-component-tags>` for managing data dependencies;
-* :ref:`Expiration based invalidation <cache-component-expiration>` for time related dependencies.
+* :ref:`Expiration based invalidation <cache-component-expiration>` for time-related dependencies.
 
 .. _cache-component-tags:
 
@@ -25,28 +25,27 @@ each cached item. Each tag is a plain string identifier that you can use at any
 time to trigger the removal of all items associated with this tag.
 
 To attach tags to cached items, you need to use the
-:method:`Symfony\\Component\\Cache\\CacheItem::tag` method that is implemented by
-cache items, as returned by cache adapters::
+:method:`Symfony\Contracts\Cache\\ItemInterface::tag` method that is implemented by
+cache items::
 
-    $item = $cache->getItem('cache_key');
-    // ...
-    // add one or more tags
-    $item->tag('tag_1');
-    $item->tag(['tag_2', 'tag_3']);
-    $cache->save($item);
+    $item = $cache->get('cache_key', function (ItemInterface $item) {
+        // [...]
+        // add one or more tags
+        $item->tag('tag_1');
+        $item->tag(['tag_2', 'tag_3']);
 
-If ``$cache`` implements :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface`,
+        return $cachedValue;
+    });
+
+If ``$cache`` implements :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`,
 you can invalidate the cached items by calling
-:method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`::
+:method:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface::invalidateTags`::
 
     // invalidate all items related to `tag_1` or `tag_3`
     $cache->invalidateTags(['tag_1', 'tag_3']);
 
     // if you know the cache key, you can also delete the item directly
-    $cache->deleteItem('cache_key');
-
-    // If you don't remember the item key, you can use the getKey() method
-    $cache->deleteItem($item->getKey());
+    $cache->delete('cache_key');
 
 Using tags invalidation is very useful when tracking cache keys becomes difficult.
 
@@ -55,7 +54,7 @@ Tag Aware Adapters
 
 To store tags, you need to wrap a cache adapter with the
 :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class or implement
-:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface` and its only
+:class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface` and its
 :method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`
 method.
 

components/cache/cache_items.rst

@@ -9,6 +9,7 @@ Cache Items
 Cache items are the information units stored in the cache as a key/value pair.
 In the Cache component they are represented by the
 :class:`Symfony\\Component\\Cache\\CacheItem` class.
+They are used in both the Cache Contracts and the PSR-6 interfaces.
 
 Cache Item Keys and Values
 --------------------------
@@ -27,14 +28,22 @@ arrays and objects.
 Creating Cache Items
 --------------------
 
-Cache items are created with the ``getItem($key)`` method of the cache pool. The
-argument is the key of the item::
+The only way to create cache items is via cache pools. When using the Cache
+Contracts, they are passed as arguments to the recomputation callback::
+
+    // $cache pool object was created before
+    $productsCount = $cache->get('stats.products_count', function (ItemInterface $item) {
+        // [...]
+    });
+
+When using PSR-6, they are created with the ``getItem($key)`` method of the cache
+pool::
 
     // $cache pool object was created before
     $productsCount = $cache->getItem('stats.products_count');
 
-Then, use the ``Psr\\Cache\\CacheItemInterface::set`` method to set
-the data stored in the cache item::
+Then, use the ``Psr\\Cache\\CacheItemInterface::set`` method to set the data stored
+in the cache item (this step is done automatically when using the Cache Contracts)::
 
     // storing a simple integer
     $productsCount->set(4711);
@@ -67,7 +76,6 @@ lifespan. Consider for example an application which caches the latest news just
 for one minute. In those cases, use the ``expiresAfter()`` method to set the
 number of seconds to cache the item::
 
-    $latestNews = $cache->getItem('latest_news');
     $latestNews->expiresAfter(60);  // 60 seconds = 1 minute
 
     // this method also accepts \DateInterval instances
@@ -76,23 +84,22 @@ number of seconds to cache the item::
 Cache items define another related method called ``expiresAt()`` to set the
 exact date and time when the item will expire::
 
-    $mostPopularNews = $cache->getItem('popular_news');
     $mostPopularNews->expiresAt(new \DateTime('tomorrow'));
 
 Cache Item Hits and Misses
 --------------------------
 
 Using a cache mechanism is important to improve the application performance, but
-it should not be required to make the application work. In fact, the PSR-6
-standard states that caching errors should not result in application failures.
+it should not be required to make the application work. In fact, the PSR-6 document
+wisely states that caching errors should not result in application failures.
 
-In practice this means that the ``getItem()`` method always returns an object
-which implements the ``Psr\Cache\CacheItemInterface`` interface, even when the
-cache item doesn't exist. Therefore, you don't have to deal with ``null`` return
+In practice with PSR-6, this means that the ``getItem()`` method always returns an
+object which implements the ``Psr\Cache\CacheItemInterface`` interface, even when
+the cache item doesn't exist. Therefore, you don't have to deal with ``null`` return
 values and you can safely store in the cache values such as ``false`` and ``null``.
 
-In order to decide if the returned object is correct or not, caches use the
-concept of hits and misses:
+In order to decide if the returned object represents a value coming from the storage
+or not, caches use the concept of hits and misses:
 
 * **Cache Hits** occur when the requested item is found in the cache, its value
   is not corrupted or invalid and it hasn't expired;