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 634902a

Browse filesBrowse files
robfrawleyrobfrawley
committed
extended prune documentation, addition of phpfiles adapter docs, rewording of some adapter text for clarity
1 parent ada9741 commit 634902a
Copy full SHA for 634902a

7 files changed

+175
-55
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
+29-9Lines changed: 29 additions & 9 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
@@ -42,8 +45,25 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
4245
new FilesystemAdapter(),
4346
));
4447

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+
4565
.. note::
4666

47-
This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
48-
for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
49-
calling it's ``prune()`` method.
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
+25-13Lines changed: 25 additions & 13 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,15 +39,18 @@ directory path, as its first, second, and third parameters::
3039
$directory = null
3140
);
3241

33-
.. tip::
42+
.. caution::
3443

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.
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.
3948

4049
.. note::
4150

42-
This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
43-
for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
44-
calling it's ``prune()`` method.
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.
54+
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
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ third, and forth parameters::
4343

4444
.. note::
4545

46-
This adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`, allowing
47-
for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
48-
calling it's ``prune()`` method.
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.
4949

5050
.. _`PDO`: http://php.net/manual/en/class.pdo.php
5151
.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php

‎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_pools.rst

Copy file name to clipboardExpand all lines: components/cache/cache_pools.rst
+44-15Lines changed: 44 additions & 15 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

@@ -144,24 +146,51 @@ Pruning Cache Items
144146

145147
.. versionadded:: 3.4
146148

147-
Pruning functionality was introduced in Symfony 3.4.
148-
149-
Some cache pools do not include an automated mechanism for pruning expired cache
150-
items. For example, :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`
151-
does not remove expired items until one is explicitly requested and determined to
152-
be expired, for example, via a call to :method:`Psr\\Cache\\CacheItemPoolInterface::getItem`.
153-
This may result in many stale cache entries persisting well past their expiration,
154-
causing a build up that can result in a sizable consumption of wasted disk or memory
155-
space.
156-
157-
This concern has been resolved through the introduction of
158-
:class:`Symfony\\Component\\Cache\\PruneableInterface`, an interface defining a
159-
singular ``prune()`` method. Relevant cache adapters, those that allow expired cache
160-
entries to proliferate, now implement ``PruneableInterface``, allowing for these
161-
excess cache entries to be manually removed::
149+
Cache adapter pruning functionality was introduced in Symfony 3.4.
150+
151+
Some cache pools do not include an automated mechanism for pruning expired cache items.
152+
For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
153+
does not remove expired cache items *until an item is explicitly requested and determined to
154+
be expired*, for example, via a call to :method:`Psr\\Cache\\CacheItemPoolInterface::getItem`.
155+
Under certain workloads, this can cause stale cache entries to persist well past their
156+
expiration, resulting in a sizable consumption of wasted disk or memory space from
157+
excess, expired cache items.
158+
159+
This shortcomming has been solved through the introduction of
160+
:class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
161+
:method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
162+
:ref:`ChainAdapter <component-cache-chain-adapter>`,
163+
:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
164+
:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
165+
:ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
166+
allowing manual removal of stale cache items::
162167

163168
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
164169

165170
$cache = new FilesystemAdapter('app.cache');
166171
// ... do some set and get operations
167172
$cache->prune();
173+
174+
The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
175+
contain any pruning logic itself. Instead, when calling the chain adapter's
176+
:method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is deligated to all
177+
its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
178+
silently ignored)::
179+
180+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
181+
use Syfmony\Component\Cache\Adapter\ChainAdapter;
182+
use Syfmony\Component\Cache\Adapter\FilesystemAdapter;
183+
use Syfmony\Component\Cache\Adapter\PdoAdapter;
184+
use Syfmony\Component\Cache\Adapter\PhpFilesAdapter;
185+
186+
$cache = new ChainAdapter(array(
187+
new ApcuAdapter(), // does NOT implement PruneableInterface
188+
new FilesystemAdapter(), // DOES implement PruneableInterface
189+
new PdoAdapter(), // DOES implement PruneableInterface
190+
new PhpFilesAdapter(), // DOES implement PruneableInterface
191+
// ...
192+
));
193+
194+
// prune will proxy the call to PdoAdapter, FilesystemAdapter and PhpFilesAdapter,
195+
// while silently skipping ApcuAdapter
196+
$cache->prune();

0 commit comments

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