8000 cleanup all cache adapter documentation, extend redis docs · symfony/symfony-docs@c49d427 · GitHub
[go: up one dir, main page]
Skip to content

Commit c49d427

Browse files
robfrawleyrobfrawley
committed
cleanup all cache adapter documentation, extend redis docs
1 parent e3eff5b commit c49d427

10 files changed

+308
-74
lines changed

‎components/cache.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
single: Performance
44
single: Components; Cache
55

6+
.. _`cache-component`:
7+
68
The Cache Component
79
===================
810

‎components/cache/adapters/apcu_adapter.rst

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,25 +2,53 @@
22
single: Cache Pool
33
single: APC Cache, APCu Cache
44

5+
.. _apcu-adapter:
6+
57
APCu Cache Adapter
68
==================
79

8-
This adapter can increase the application performance very significantly,
9-
because contents are cached in the shared memory of your server, which is much
10-
faster than the file system. It requires to have installed and enabled the PHP
11-
APCu extension. It's not recommended to use it when performing lots of write and
12-
delete operations because it produces fragmentation in the APCu memory that can
13-
degrade performance significantly::
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 file system.
14+
15+
.. caution::
16+
17+
**Requirement:** The `APCu extension`_ must be installed and active to use
18+
this adapter.
19+
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::
1423

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

1726
$cache = new ApcuAdapter(
18-
// the string prefixed to the keys of the items stored in this cache
27+
28+
// a string prefixed to the keys of the items stored in this cache
1929
$namespace = '',
20-
// in seconds; applied to cache items that don't define their own lifetime
21-
// 0 means to store the cache items indefinitely (i.e. until the APC memory is deleted)
30+
31+
// the default lifetime (in seconds) for cache items that do not define their
32+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
33+
// until the APCu memory is cleared)
2234
$defaultLifetime = 0,
23-
// if present, this string is added to the namespace to simplify the
24-
// invalidation of the entire cache (e.g. when deploying the application)
35+
36+
// when set, all keys prefixed by $namespace can be invalidated by changing
37+
// this $version string
2538
$version = null
2639
);
40+
41+
.. caution::
42+
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.
46+
47+
.. tip::
48+
49+
Note that this adapters 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.
53+
54+
.. _`APCu extension`: https://pecl.php.net/package/APCu

‎components/cache/adapters/array_cache_adapter.rst

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,23 @@
55
Array Cache Adapter
66
===================
77

8-
This adapter is only useful for testing purposes because contents are stored in
9-
memory and not persisted in any way. Besides, some features explained later are
10-
not available, such as the deferred saves::
8+
Generally, this adapter is useful for testing purposes, as its contents are stored in memory
9+
and not persisted outside the running PHP process in any way. It can also be useful while
10+
warming up caches, due to the :method:`Symfony\\Component\\Cache\\Adapter\\ArrayAdapter::getValues`
11+
method.
12+
13+
This adapter can be passed a default cache lifetime as its first parameter, and a boolean that
14+
toggles serialization as its second parameter::
1115

1216
use Symfony\Component\Cache\Adapter\ArrayAdapter;
1317

1418
$cache = new ArrayAdapter(
15-
// in seconds; applied to cache items that don't define their own lifetime
16-
// 0 means to store the cache items indefinitely (i.e. until the current PHP process finishes)
19+
20+
// the default lifetime (in seconds) for cache items that do not define their
21+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
22+
// until the current PHP process finishes)
1723
$defaultLifetime = 0,
24+
1825
// if ``true``, the values saved in the cache are serialized before storing them
1926
$storeSerialized = true
2027
);

‎components/cache/adapters/chain_adapter.rst

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDif 10000 f line change
@@ -5,22 +5,39 @@
55
Chain Cache Adapter
66
===================
77

8-
This adapter allows to combine any number of the previous adapters. Cache items
9-
are fetched from the first adapter which contains them. Besides, cache items are
10-
saved in all the given adapters, so this is a simple way of creating a cache
11-
replication::
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.
11+
12+
This adapter expects an array of adapters as its first parameter, and optionally a
13+
maximum cache lifetime as its second parameter::
1214

1315
use Symfony\Component\Cache\Adapter\ApcuAdapter;
14-
use Symfony\Component\Cache\Adapter\ChainAdapter;
15-
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1616

17-
$apcCache = new ApcuAdapter();
18-
$fileCache = new FilesystemAdapter();
17+
$cache = new ChainAdapter(array(
18+
19+
// The ordered list of adapters used to fetch cached items
20+
array $adapters,
21+
22+
// The max lifetime of items propagated from lower adapters to upper ones
23+
$maxLifetime = 0
24+
));
25+
26+
.. note::
1927

20-
$cache = new ChainAdapter(array($apcCache, $fileCache));
28+
When an item is not found in the first adapters but is found in the next ones, this
29+
adapter ensures that the fetched item is saved in all the adapters where it was
30+
previously missing.
31+
32+
The following shows how to create a chain adapter instance using the fastest and slowest
33+
storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter` and
34+
:class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`, respectfully::
35+
36+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
37+
use Symfony\Component\Cache\Adapter\ChainAdapter;
38+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
2139

22-
When an item is not found in the first adapters but is found in the next ones,
23-
the ``ChainAdapter`` ensures that the fetched item is saved in all the adapters
24-
where it was missing. Since it's not possible to know the expiry date and time
25-
of a cache item, the second optional argument of ``ChainAdapter`` is the default
26-
lifetime applied to those cache items (by default it's ``0``).
40+
$cache = new ChainAdapter(array(
41+
new ApcuAdapter(),
42+
new FilesystemAdapter(),
43+
));

‎components/cache/adapters/doctrine_adapter.rst

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,36 @@
22
single: Cache Pool
33
single: Doctrine Cache
44

5+
.. _`doctrine-adapter`:
6+
57
Doctrine Cache Adapter
68
======================
79

8-
This adapter wraps any `Doctrine Cache`_ provider so you can use them in your
9-
application as if they were Symfony Cache adapters::
10+
This adapter wraps any class extending the `Doctrine Cache`_ abstract provider, allowing
11+
you to use these providers in your application as if they were Symfony Cache adapters.
12+
13+
This adapter expects a ``\Doctrine\Common\Cache\CacheProvider`` instance as its first
14+
parameter, and optionally a namespace and default cache lifetime as its second and
15+
third parameters::
1016

17+
use Doctrine\Common\Cache\CacheProvider;
1118
use Doctrine\Common\Cache\SQLite3Cache;
1219
use Symfony\Component\Cache\Adapter\DoctrineAdapter;
1320

14-
$sqliteDatabase = new \SQLite3(__DIR__.'/cache/data.sqlite');
15-
$doctrineCache = new SQLite3Cache($sqliteDatabase, 'tableName');
16-
$symfonyCache = new DoctrineAdapter($doctrineCache);
21+
$provider = new SQLite3Cache(new \SQLite3(__DIR__.'/cache/data.sqlite'), 'youTableName');
22+
23+
$symfonyCache = new DoctrineAdapter(
24+
25+
// a cache provider instance
26+
CacheProvider $provider,
27+
28+
// a string prefixed to the keys of the items stored in this cache
29+
$namespace = '',
1730

18-
This adapter also defines two optional arguments called ``namespace`` (default:
19-
``''``) and ``defaultLifetime`` (default: ``0``) and adapts them to make them
20-
work in the underlying Doctrine cache.
31+
// the default lifetime (in seconds) for cache items that do not define their
32+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
33+
// until the database table is truncated or its rows are otherwise deleted)
34+
$defaultLifetime = 0
35+
);
2136

2237
.. _`Doctrine Cache`: https://github.com/doctrine/cache

‎components/cache/adapters/filesystem_adapter.rst

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,33 @@ Filesystem Cache Adapter
66
========================
77

88
This adapter is useful when you want to improve the application performance but
9-
can't install tools like APCu or Redis in the server. This adapter stores the
10-
contents as regular files in a set of directories on the local file system::
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.
11+
12+
This adapter can optionally be provided a namespace, default cache lifetime, and
13+
directory path, as its first, second, and third parameters::
1114

1215
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1316

1417
$cache = new FilesystemAdapter(
15-
// the subdirectory of the main cache directory where cache items are stored
18+
19+
// a string used as the subdirectory of the root cache directory, where cache
20+
// items will be stored
1621
$namespace = '',
17-
// in seconds; applied to cache items that don't define their own lifetime
18-
// 0 means to store the cache items indefinitely (i.e. until the files are deleted)
22+
23+
// the default lifetime (in seconds) for cache items that do not define their
24+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
25+
// until the files are deleted)
1926
$defaultLifetime = 0,
27+
2028
// the main cache directory (the application needs read-write permissions on it)
2129
// if none is specified, a directory is created inside the system temporary directory
2230
$directory = null
2331
);
32+
33+
.. tip::
34+
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.

‎components/cache/adapters/memcached_adapter.rst

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
single: Cache Pool
33
single: Memcached Cache
44

5+
.. _memcached-adapter:
6+
57
Memcached Cache Adapter
68
=======================
79

@@ -10,15 +12,17 @@ Memcached Cache Adapter
1012
The Memcached adapter was introduced in Symfony 3.3.
1113

1214
This adapter stores the values in-memory using one (or more) `Memcached server`_
13-
instances. Unlike the ACPu adapter, and similarly to the Redis adapter, it is
14-
not limited to the current server's shared memory; you can store contents
15-
independent of your PHP environment. The ability to utilize a cluster of servers
16-
to provide redundancy and/or fail-over is also available.
15+
instances. Unlike the :ref:`APCu adapter <apcu-adapter>`, and similarly to the
16+
:ref:`Redis adapter <redis-adapter>`, it is not limited to the current server's
17+
shared memory; you can store contents independent of your PHP environment.
18+
The ability to utilize a cluster of servers to provide redundancy and/or fail-over
19+
is also available.
1720

1821
.. caution::
1922

20-
The `Memcached PHP extension`_ as well as a `Memcached server`_ must be
21-
installed, active, and running to use this adapter.
23+
**Requirements:** The `Memcached PHP extension`_ as well as a `Memcached server`_
24+
must be installed, active, and running to use this adapter. Version ``2.2`` or
25+
greater of the `Memcached PHP extension`_ is required for this adapter.
2226

2327
This adapter expects a `Memcached`_ instance to be passed as the first
2428
parameter. A namespace and default cache lifetime can optionally be passed as
@@ -71,7 +75,7 @@ The DSN must include a IP/host (and an optional port) or a socket path, an
7175
optional username and password (for SASL authentication; it requires that the
7276
memcached extension was compiled with ``--enable-memcached-sasl``) and an
7377
optional weight (for prioritizing servers in a cluster; its value is an integer
74-
between ``0`` and ``100`` which defaults to ``XX``; a higher value means more
78+
between ``0`` and ``100`` which defaults to ``null``; a higher value means more
7579
priority).
7680

7781
Below are common examples of valid DSNs showing a combination of available values::
@@ -201,7 +205,7 @@ Available Options
201205
expense of more write traffic.
202206

203207
``recv_timeout`` (type: ``int``, default: ``0``)
204-
Specifies he amount of time (in microseconds) before timing out during an outgoing socket (read) operation.
208+
Specifies the amount of time (in microseconds) before timing out during an outgoing socket (read) operation.
205209
When the ``no_block`` option isn't enabled, this will allow you to still have timeouts on the reading of data.
206210

207211
Valid option values include ``0`` or *any positive integer*.
@@ -275,7 +279,7 @@ Available Options
275279
are valid and fit within the design of the protocol being used.
276280

277281
.. tip::
278-
Reference the `Memcached extension`_'s `predefined constants`_ documentation
282+
Reference the `Memcached`_ extension's `predefined constants`_ documentation
279283
for additional information about the available options.
280284

281285
.. _`Transmission Control Protocol (TCP)`: https://en.wikipedia.org/wiki/Transmission_Control_Protocol

‎components/cache/adapters/pdo_doctrine_dbal_adapter.rst

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
single: Cache Pool
33
single: PDO Cache, Doctrine DBAL Cache
44

5+
.. _`pdo-doctrine-adapter`:
6+
57
PDO & Doctrine DBAL Cache Adapter
68
=================================
79

@@ -10,19 +12,35 @@ PDO & Doctrine DBAL Cache Adapter
1012
The PDO & Doctrine DBAL adapter was introduced in Symfony 3.2.
1113

1214

13-
This adapter stores the cached items a SQL database accessed through a PDO or a
14-
Doctrine DBAL connection::
15+
This adapter stores the cache items in an SQL database. It requires a `PDO`_,
16+
`Doctrine DBAL Connection`_, or `Data Source Name (DSN)`_ as its first parameter, and
17+
optionally a namespace, default cache lifetime, and options array as its second,
18+
third, and forth parameters::
1519

1620
use Symfony\Component\Cache\Adapter\PdoAdapter;
1721

1822
$cache = new PdoAdapter(
23+
1924
// a PDO, a Doctrine DBAL connection or DSN for lazy connecting through PDO
2025
$databaseConnectionOrDSN,
26+
2127
// the string prefixed to the keys of the items stored in this cache
2228
$namespace = '',
23-
// in seconds; applied to cache items that don't define their own lifetime
24-
// 0 means to store the cache items indefinitely (i.e. until the database is cleared)
29+
30+
// the default lifetime (in seconds) for cache items that do not define their
31+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
32+
// until the database table is truncated or its rows are otherwise deleted)
2533
$defaultLifetime = 0,
34+
2635
// an array of options for configuring the database connection
2736
$options = array()
2837
);
38+
39+
.. tip::
40+
41+
When passed a `Data Source Name (DSN)`_ string (instead of a database connection
42+
class instance), the connection will be lazy-loaded when needed.
43+
44+
.. _`PDO`: http://php.net/manual/en/class.pdo.php
45+
.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
46+
.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

‎components/cache/adapters/proxy_adapter.rst

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,32 @@
55
Proxy Cache Adapter
66
===================
77

8-
This adapter is useful to integrate in your application cache pools not created
9-
with the Symfony Cache component. As long as those cache pools implement the
10-
``CacheItemPoolInterface`` interface, this adapter allows you to get items from
11-
that external cache and save them in the Symfony cache of your application::
8+
This adapter wraps a `PSR-6`_ compliant `cache item pool interface`_. It is used to integrate
9+
your application's cache item pool implementation with the Symfony :ref:`Cache Component <cache-component>`
10+
by consuming any implementation of ``Psr\Cache\CacheItemPoolInterface``.
1211

12+
This adapter expects a ``Psr\Cache\CacheItemPoolInterface`` instance as its first parameter,
13+
and optionally a namespace and default cache lifetime as its second and third parameters::
14+
15+
use Psr\Cache\CacheItemPoolInterface;
1316
use Symfony\Component\Cache\Adapter\ProxyAdapter;
1417

15-
// ... create $nonSymfonyCache somehow
16-
$cache = new ProxyAdapter($nonSymfonyCache);
18+
$psr6CachePool = \\ create your own cache pool instance that implements the PSR-6
19+
\\ interface `CacheItemPoolInterface`
20+
21+
$cache = new ProxyAdapter(
22+
23+
// a cache pool instance
24+
CacheItemPoolInterface $psr6CachePool,
25+
26+
// a string prefixed to the keys of the items stored in this cache
27+
$namespace = '',
28+
29+
// the default lifetime (in seconds) for cache items that do not define their
30+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
31+
// until the cache is cleared)
32+
$defaultLifetime = 0
33+
);
1734

18-
The adapter accepts two additional optional arguments: the namespace (``''`` by
19-
default) and the default lifetime (``0`` by default).
35+
.. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
36+
.. _`cache item pool interface`: http://www.php-fig.org/psr/psr-6/#cacheitempoolinterface

0 commit comments

Comments
 (0)
0