8000 extended prune documentation, addition of phpfiles adapter docs, rewo… · symfony/symfony-docs@634902a · GitHub
[go: up one dir, main page]
Skip to content

Commit 634902a

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

File tree

7 files changed

+175
-55
lines changed

7 files changed

+175
-55
lines changed

‎components/cache/adapters/apcu_adapter.rst‎

Lines 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‎

Lines 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‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,24 @@
22< 6187 /code>
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‎

Lines 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‎

Lines 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‎

Lines 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‎

Lines 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