First round of fixes

components/cache/cache_items.rst

@@ -6,8 +6,8 @@
 Cache Items
 ===========
 
-Cache items are each one of the information units stored in the cache as a
-key/value pair. In the Cache component they are represented by the
+Cache items are each of 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.
 
 Cache Item Keys and Values
@@ -18,13 +18,14 @@ identifier, so it must be unique for each cache pool. The PSR-6 standard limits
 the key length to 64 characters, but Symfony allows to use longer keys (they are
 encoded internally to reduce their size).
 
-You can freely chose the keys, but they can only contain letters (A-Z, a-z),
+You can freely choose the keys, but they should only contain letters (A-Z, a-z),
 numbers (0-9) and the ``_`` and ``.`` symbols. Other common symbols (such as
-``{``, ``}``, ``(``, ``)``, ``/``, ``\`` and ``@``) are reserved for future uses.
+``{``, ``}``, ``(``, ``)``, ``/``, ``\`` and ``@``) are reserved by the PSR-6
+standard for future uses.
 
 The **value** of a cache item can be any data represented by a type which is
-serializable by PHP, such as basic types (strings, integers, floats, boolean,
-nulls), arrays and objects.
+serializable by PHP, such as basic types (strings, integers, floats, booleans,
+null), arrays and objects.
 
 Creating Cache Items
 --------------------
@@ -63,8 +64,9 @@ corresponding *getter* methods::
 Cache Item Expiration
 ~~~~~~~~~~~~~~~~~~~~~
 
-By default cache items are stored "permanently", which in practice means "as long
-as allowed by the cache implementation used".
+By default cache items are stored permanently. In practice, this "permanent
+storage" can vary greatly depending on the type of cache being used, as
+explained in the :doc:`/cookbook/cache/cache_pools` article.
 
 However, in some applications it's common to use cache items with a shorter
 lifespan. Consider for example an application which caches the latest news just
@@ -92,7 +94,8 @@ standard 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`` values.
+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:
@@ -107,10 +110,10 @@ Cache item objects define a boolean ``isHit()`` method which returns ``true``
 for cache hits::
 
  $latestNews = $cache->getItem('latest_news');
- $latestNews->expiresAfter(60);
 
- // check the item a few seconds after creating it
- $isHit = $latestNews->isHit(); // true
-
- // check the item 10 minutes after creating it
- $isHit = $latestNews->isHit(); // false
+ if (!$latestNews->isHit()) {
+ $news = //... do some heavy computation
+ $cache->save($latestNews->set($news));
+ } else {
+ $news = $latestNews->get();
+ }

components/cache/cache_pools.rst

@@ -24,7 +24,7 @@ Array Cache Adapter
 ~~~~~~~~~~~~~~~~~~~
 
 This adapter is only useful for testing purposes because contents are stored in
-memory and no persisted in any way. Besides, some features explained later are
+memory and not persisted in any way. Besides, some features explained later are
 not available, such as the deferred saves::
 
  use Symfony\Component\Cache\Adapter\ArrayAdapter;
@@ -45,7 +45,8 @@ Filesystem Cache Adapter
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 This adapter is useful when you want to improve the application performance but
-can't install in the server tools like APC or Redis::
+can't install tools like APC or Redis in the server. This adapter stores the
+contents as regular files in a set of directories on the local file system::
 
  use Symfony\Component\Cache\Adapter\FilesystemAdapter;
 
@@ -74,7 +75,10 @@ APCu Cache Adapter
 
 This adapter can increase the application performance very significantly, because
 contents are cached in the memory of your server, which is much faster than the
-filesystem. It requires to have installed and enabled the PHP APC extension::
+file system. It requires to have installed and enabled the PHP APC extension.
+It's not recommended to use it when performing lots of write and delete
+operations because it produces fragmentation in the APCu memory and that
+degrades performance significantly::
 
  use Symfony\Component\Cache\Adapter\ApcuAdapter;
 
@@ -97,7 +101,7 @@ Redis Cache Adapter
 This adapter, similarly to APCu adapter, can increase the application performance
 very significantly, because contents are cached in the memory of your server. It
 requires to have installed Redis and have created a connection that implements
-``\Redis`` class::
+the ``\Redis`` class::
 
  use Symfony\Component\Cache\Adapter\RedisAdapter;