Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit adb411e

Browse filesBrowse files
robfrawleyrobfrawley
committed
document cache pruning functionality
- note the addition of PruneableInterface - note the variouse, concrete PruneableInterface::prune() implementations in ChainAdapter, FilesystemAdapter, PdoAdapter, PhpFilesAdapter, ChainCache, FilesystemCache, PdoCache, PhpFilesCache, and TagAwareAdapter. - note the addition of CachePoolPruneCommand, invokable via cache:pool:prune. This command iterates over all services tagged cache.pool and calls the PruneableInterface::prune() method on those that implement PruneableInterface - rewording of some adapter text for clarity - additional note blocks for all caches that implement PruneableInterface - addition of prune() description and usage example on the chain adapter - addition of a tip about achieving better performance with the filesystem adapter by utilizing tmpfs or another ram disk solution - fix for an incorrect use statement in the PHP array cache adapter code example - addition of documentation page for PHP files adapter - addition of a "pruning cache items" explanation and example on the main cache pools page
1 parent d410c46 commit adb411e
Copy full SHA for adb411e

9 files changed

+223
-35
lines changed

‎components/cache/adapters/apcu_adapter.rst

Copy file name to clipboardExpand all lines: components/cache/adapters/apcu_adapter.rst
+10-14Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,17 @@
77
APCu Cache Adapter
88
==================
99

10-
This adapter is a high-performance, shared memory cache. It can increase the
11-
application performance very significantly because the cache contents are
12-
stored in the shared memory of your server, a component that is much faster than
13-
others, such as the filesystem.
10+
This adapter is a high-performance, shared memory cache. It can *significantly* increase
11+
an application's performance, as its cache contents are stored in shared memory, a component
12+
appreciably faster than many others, such as the filesystem.
1413

1514
.. caution::
1615

1716
**Requirement:** The `APCu extension`_ must be installed and active to use
1817
this adapter.
1918

20-
This adapter can be provided an optional namespace string as its first parameter, a
21-
default cache lifetime as its second parameter, and a version string as its third
22-
parameter::
19+
The ApcuAdapter can optionally be provided a namespace, default cache lifetime, and cache
20+
items version string as constructor arguments::
2321

2422
use Symfony\Component\Cache\Adapter\ApcuAdapter;
2523

@@ -40,15 +38,13 @@ parameter::
4038

4139
.. caution::
4240

43-
It is *not* recommended to use this adapter when performing a large number of
44-
write and delete operations, as these operations result in fragmentation of the
45-
APCu memory, resulting in *significantly* degraded performance.
41+
Use of this adapter is discouraged in write/delete heavy workloads, as these
42+
operations cause memory fragmentation that results in significantly degraded performance.
4643

4744
.. tip::
4845

49-
Note that this adapter's CRUD operations are specific to the PHP SAPI it is running
50-
under. This means adding a cache item using the CLI will not result in the item
51-
appearing under FPM. Likewise, deletion of an item using CGI will not result in the
52-
item being deleted under the CLI.
46+
This adapter's CRUD operations are specific to the PHP SAPI it is running under. This
47+
means cache operations (such as additions, deletions, etc) using the CLI will not be
48+
available under the FPM or CGI SAPIs.
5349

5450
.. _`APCu extension`: https://pecl.php.net/package/APCu

‎components/cache/adapters/chain_adapter.rst

Copy file name to clipboardExpand all lines: components/cache/adapters/chain_adapter.rst
+32-6Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,18 @@
22
single: Cache Pool
33
single: Chain Cache
44

5+
.. _component-cache-chain-adapter:
6+
57
Chain Cache Adapter
68
===================
79

8-
This adapter allows to combine any number of the other available cache adapters.
9-
Cache items are fetched from the first adapter which contains them and cache items are
10-
saved in all the given adapters. This offers a simple way of creating a layered cache.
10+
This adapter allows combining any number of the other
11+
:ref:`available cache adapters <component-cache-creating-cache-pools>`. Cache items are
12+
fetched from the first adapter containing them and cache items are saved to all the
13+
given adapters. This exposes a simple and efficient method for creating a layeted cache.
1114

12-
This adapter expects an array of adapters as its first parameter, and optionally a
13-
maximum cache lifetime as its second parameter::
15+
The ChainAdapter must be provided an array of adapters and optionally a maximum cache
16+
lifetime as its constructor arguments::
1417

1518
use Symfony\Component\Cache\Adapter\ApcuAdapter;
1619

@@ -26,7 +29,7 @@ maximum cache lifetime as its second parameter::
2629
.. note::
2730

2831
When an item is not found in the first adapter but is found in the next ones, this
29-
adapter ensures that the fetched item is saved in all the adapters where it was
32+
adapter ensures that the fetched item is saved to all the adapters where it was
3033
previously missing.
3134

3235
The following example shows how to create a chain adapter instance using the fastest and
@@ -41,3 +44,26 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
4144
new ApcuAdapter(),
4245
new FilesystemAdapter(),
4346
));
47+
48+
When calling this adapter's :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method,
49+
the call is deligated to all its compatibe cache adapters. It is safe to mix both adapters
50+
that *do* and do *not* implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, as
51+
incompatible adapters are silently ignored::
52+
53+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
54+
use Symfony\Component\Cache\Adapter\ChainAdapter;
55+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
56+
57+
$cache = new ChainAdapter(array(
58+
new ApcuAdapter(), // does NOT implement PruneableInterface
59+
new FilesystemAdapter(), // DOES implement PruneableInterface
60+
));
61+
62+
// prune will proxy the call to FilesystemAdapter while silently skipping ApcuAdapter
63+
$cache->prune();
64+
65+
.. note::
66+
67+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
68+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
69+
calling its ``prune()`` method.

‎components/cache/adapters/filesystem_adapter.rst

Copy file name to clipboardExpand all lines: components/cache/adapters/filesystem_adapter.rst
+28-10Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,24 @@
22
single: Cache Pool
33
single: Filesystem Cache
44

5+
.. _component-cache-filesystem-adapter:
6+
57
Filesystem Cache Adapter
68
========================
79

8-
This adapter is useful when you want to improve the application performance but
9-
can't install tools like APCu or Redis on the server. This adapter stores the
10-
contents as regular files in a set of directories on the local file system.
10+
This adapter offers improved application performance for those who cannot install
11+
tools like :ref:`APCu <apcu-adapter>` or :ref:`Redis <redis-adapter>` in their
12+
environment. It stores the cache item expiration and content as regular files in
13+
a collection of directories on a locally mounted filesystem.
14+
15+
.. tip::
16+
17+
The performance of this adapter can be greatly increased by utalizing a
18+
temporary, in-memory filesystem, such as `tmpfs`_ on Linux, or one of the
19+
many other `RAM disk solutions`_ available.
1120

12-
This adapter can optionally be provided a namespace, default cache lifetime, and
13-
directory path, as its first, second, and third parameters::
21+
The FilesystemAdapter can optionally be provided a namespace, default cache lifetime,
22+
and cache root path as constructor parameters::
1423

1524
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1625

@@ -30,9 +39,18 @@ directory path, as its first, second, and third parameters::
3039
$directory = null
3140
);
3241

33-
.. tip::
42+
.. caution::
43+
44+
The overhead of filesystem IO often makes this adapter one of the *slower* choices. If throughput is
45+
paramount, the in-memory adapters (:ref:`Apcu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`,
46+
and :ref:`Redis <redis-adapter>`) or the database adapters (:ref:`Doctrine <doctrine-adapter>` and
47+
:ref:`PDO <pdo-doctrine-adapter>`) are recommended.
48+
49+
.. note::
50+
51+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
52+
enabling manual :ref:`pruning of expired cache items <component-cache-cache-pool-prune>` by
53+
calling its ``prune()`` method.
3454

35-
This adapter is generally the *slowest* due to the overhead of file IO. If throughput is paramount,
36-
the in-memory adapters (such as :ref:`APCu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`,
37-
and :ref:`Redis <redis-adapter>`) or the database adapters (such as
38-
:ref:`Doctrine <doctrine-adapter>` and :ref:`PDO & Doctrine <pdo-doctrine-adapter>`) are recommended.
55+
.. _`tmpfs`: https://wiki.archlinux.org/index.php/tmpfs
56+
.. _`RAM disk solutions`: https://en.wikipedia.org/wiki/List_of_RAM_drive_software

‎components/cache/adapters/pdo_doctrine_dbal_adapter.rst

Copy file name to clipboardExpand all lines: components/cache/adapters/pdo_doctrine_dbal_adapter.rst
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ third, and forth parameters::
4141
When passed a `Data Source Name (DSN)`_ string (instead of a database connection
4242
class instance), the connection will be lazy-loaded when needed.
4343

44+
.. note::
45+
46+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
47+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
48+
calling its ``prune()`` method.
49+
4450
.. _`PDO`: http://php.net/manual/en/class.pdo.php
4551
.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
4652
.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

‎components/cache/adapters/php_array_cache_adapter.rst

Copy file name to clipboardExpand all lines: components/cache/adapters/php_array_cache_adapter.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This adapter is a highly performant way to cache static data (e.g. application c
99
that is optimized and preloaded into OPcache memory storage::
1010

1111
use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
12-
use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
12+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1313

1414
// somehow, decide it's time to warm up the cache!
1515
if ($needsWarmup) {

‎components/cache/adapters/php_files_adapter.rst

Copy file name to clipboard
+63Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. index::
2+
single: Cache Pool
3+
single: PHP Files Cache
4+
5+
.. _component-cache-files-adapter:
6+
7+
Php Files Cache Adapter
8+
=======================
9+
10+
Similarly to :ref:`Filesystem Adapter <component-cache-filesystem-adapter>`, this cache
11+
implementation writes cache entries out to disk, but unlike the Filesystem cache adapter,
12+
the PHP Files cache adapter writes and reads back these cache files *as native PHP code*.
13+
For example, caching the value ``array('my', 'cached', 'array')`` will write out a cache
14+
file similar to the following::
15+
16+
<?php return array(
17+
18+
// the cache item expiration
19+
0 => 9223372036854775807,
20+
21+
// the cache item contents
22+
1 => array (
23+
0 => 'my',
24+
1 => 'cached',
25+
2 => 'array',
26+
),
27+
28+
);
29+
30+
.. note::
31+
32+
As cache items are included and parsed as native PHP code and due to the way `OPcache`_
33+
handles file includes, this adapter has the potential to be much faster than other
34+
filesystem-based caches.
35+
36+
The PhpFilesAdapter can optionally be provided a namespace, default cache lifetime, and cache
37+
directory path as constructor arguments::
38+
39+
use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
40+
41+
$cache = new PhpFilesAdapter(
42+
43+
// a string used as the subdirectory of the root cache directory, where cache
44+
// items will be stored
45+
$namespace = '',
46+
47+
// the default lifetime (in seconds) for cache items that do not define their
48+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
49+
// until the files are deleted)
50+
$defaultLifetime = 0,
51+
52+
// the main cache directory (the application needs read-write permissions on it)
53+
// if none is specified, a directory is created inside the system temporary directory
54+
$directory = null
55+
);
56+
57+
.. note::
58+
59+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
60+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
61+
calling its ``prune()`` method.
62+
63+
.. _`OPcache`: http://php.net/manual/en/book.opcache.php

‎components/cache/cache_invalidation.rst

Copy file name to clipboardExpand all lines: components/cache/cache_invalidation.rst
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,16 @@ your fronts and have very fast invalidation checks::
8080
new RedisAdapter('redis://localhost')
8181
);
8282

83+
.. note::
84+
85+
Since Symfony 3.4, :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
86+
implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
87+
enabling manual
88+
:ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
89+
calling its :method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter::prune`
90+
method (assuming the wrapped adapter itself implements
91+
:class:`Symfony\\Component\\Cache\\PruneableInterface`).
92+
8393
.. _cache-component-expiration:
8494

8595
Using Cache Expiration

‎components/cache/cache_pools.rst

Copy file name to clipboardExpand all lines: components/cache/cache_pools.rst
+71-4Lines changed: 71 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ are independent from the actual cache implementation. Therefore, applications
2020
can keep using the same cache pool even if the underlying cache mechanism
2121
changes from a file system based cache to a Redis or database based cache.
2222

23+
.. _component-cache-creating-cache-pools:
24+
2325
Creating Cache Pools
2426
--------------------
2527

@@ -124,17 +126,82 @@ when all items are successfully deleted)::
124126

125127
.. tip::
126128

127-
If the Cache component is used inside a Symfony application, you can remove
128-
all the items of a given cache pool with the following command:
129+
If the cache component is used inside a Symfony application, you can remove
130+
*all items* from the *given pool(s)* using the following command (which resides within
131+
the :ref:`framework bundle <framework-bundle-configuration>`):
129132

130133
.. code-block:: terminal
131134
132135
$ php bin/console cache:pool:clear <cache-pool-name>
133-
136+
134137
# clears the "cache.app" pool
135138
$ php bin/console cache:pool:clear cache.app
136139
137140
# clears the "cache.validation" and "cache.app" pool
138141
$ php bin/console cache:pool:clear cache.validation cache.app
139142
140-
.. _`Doctrine Cache`: https://github.com/doctrine/cache
143+
.. _component-cache-cache-pool-prune:
144+
145+
Pruning Cache Items
146+
-------------------
147+
148+
.. versionadded:: 3.4
149+
150+
Cache adapter pruning functionality was introduced in Symfony 3.4.
151+
152+
Some cache pools do not include an automated mechanism for pruning expired cache items.
153+
For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
154+
does not remove expired cache items *until an item is explicitly requested and determined to
155+
be expired*, for example, via a call to :method:`Psr\\Cache\\CacheItemPoolInterface::getItem`.
156+
Under certain workloads, this can cause stale cache entries to persist well past their
157+
expiration, resulting in a sizable consumption of wasted disk or memory space from
158+
excess, expired cache items.
159+
160+
This shortcomming has been solved through the introduction of
161+
:class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
162+
:method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
163+
:ref:`ChainAdapter <component-cache-chain-adapter>`,
164+
:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
165+
:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
166+
:ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
167+
allowing manual removal of stale cache items::
168+
169+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
170+
171+
$cache = new FilesystemAdapter('app.cache');
172+
// ... do some set and get operations
173+
$cache->prune();
174+
175+
The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
176+
contain any pruning logic itself. Instead, when calling the chain adapter's
177+
:method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is deligated to all
178+
its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
179+
silently ignored)::
180+
181+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
182+
use Syfmony\Component\Cache\Adapter\ChainAdapter;
183+
use Syfmony\Component\Cache\Adapter\FilesystemAdapter;
184+
use Syfmony\Component\Cache\Adapter\PdoAdapter;
185+
use Syfmony\Component\Cache\Adapter\PhpFilesAdapter;
186+
187+
$cache = new ChainAdapter(array(
188+
new ApcuAdapter(), // does NOT implement PruneableInterface
189+
new FilesystemAdapter(), // DOES implement PruneableInterface
190+
new PdoAdapter(), // DOES implement PruneableInterface
191+
new PhpFilesAdapter(), // DOES implement PruneableInterface
192+
// ...
193+
));
194+
195+
// prune will proxy the call to PdoAdapter, FilesystemAdapter and PhpFilesAdapter,
196+
// while silently skipping ApcuAdapter
197+
$cache->prune();
198+
199+
.. tip::
200+
201+
If the cache component is used inside a Symfony application, you can prune
202+
*all items* from *all pools* using the following command (which resides within
203+
the :ref:`framework bundle <framework-bundle-configuration>`):
204+
205+
.. code-block:: terminal
206+
207+
$ php bin/console cache:pool:prune

‎reference/configuration/framework.rst

Copy file name to clipboardExpand all lines: reference/configuration/framework.rst
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
.. index::
22
single: Configuration reference; Framework
33

4+
.. _framework-bundle-configuration:
5+
46
FrameworkBundle Configuration ("framework")
57
===========================================
68

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.