initial documentation for cache pruning functionality

Author: robfrawley

components/cache/adapters/chain_adapter.rst

@@ -41,3 +41,9 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
         new ApcuAdapter(),
         new FilesystemAdapter(),
     ));
+
+.. note::
+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
+    for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
+    calling it's ``prune()`` method.

components/cache/adapters/filesystem_adapter.rst

@@ -36,3 +36,9 @@ directory path, as its first, second, and third parameters::
     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.
+
+.. note::
+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
+    for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
+    calling it's ``prune()`` method.

components/cache/adapters/pdo_doctrine_dbal_adapter.rst

@@ -41,6 +41,12 @@ third, and forth parameters::
     When passed a `Data Source Name (DSN)`_ string (instead of a database connection
     class instance), the connection will be lazy-loaded when needed.
 
+.. note::
+
+    This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
+    for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
+    calling it's ``prune()`` method.
+
 .. _`PDO`: http://php.net/manual/en/class.pdo.php
 .. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
 .. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

components/cache/cache_pools.rst

@@ -137,4 +137,31 @@ when all items are successfully deleted)::
         # clears the "cache.validation" and "cache.app" pool
         $ php bin/console cache:pool:clear cache.validation cache.app
 
-.. _`Doctrine Cache`: https://github.com/doctrine/cache
+.. _component-cache-cache-pool-prune:
+
+Pruning Cache Items
+-------------------
+
+.. versionadded:: 3.4
+
+    Pruning functionality was introduced in Symfony 3.4.
+
+Some cache pools do not include an automated mechanism for pruning expired cache
+items. For example, :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`
+does not remove expired items until one is explicitly requested and determined to
+be expired, for example, via a call to :method:`Psr\\Cache\\CacheItemPoolInterface::getItem`.
+This may result in many stale cache entries persisting well past their expiration,
+causing a build up that can result in a sizable consumption of wasted disk or memory
+space.
+
+This concern has been resolved through the introduction of 
+:class:`Symfony\\Component\\Cache\\PruneableInterface`, an interface defining a
+singular ``prune()`` method. Relevant cache adapters, those that allow expired cache
+entries to proliferate, now implement ``PruneableInterface``, allowing for these
+excess cache entries to be manually removed::
+
+    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
+
+    $cache = new FilesystemAdapter('app.cache');
+    // ... do some set and get operations
+    $cache->prune();