initial documentation for cache pruning

robfrawley · robfrawley · commit 397ef144898d · 2017-07-21T22:58:16.000-04:00
diff --git a/components/cache/adapters/chain_adapter.rst b/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.
diff --git a/components/cache/adapters/filesystem_adapter.rst b/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.
diff --git a/components/cache/adapters/pdo_doctrine_dbal_adapter.rst b/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
diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst
@@ -121,3 +121,32 @@ when all items are successfully deleted)::
 
     // ...
     $cacheIsEmpty = $cache->clear();
+
+.. _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();
