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 c49d427

Browse filesBrowse files
robfrawleyrobfrawley
committed
cleanup all cache adapter documentation, extend redis docs
1 parent e3eff5b commit c49d427
Copy full SHA for c49d427

10 files changed

+308
-74
lines changed

‎components/cache.rst

Copy file name to clipboardExpand all lines: components/cache.rst
+2Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/apcu_adapter.rst
+39-11Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/array_cache_adapter.rst
+12-5Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/chain_adapter.rst
+31-14Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff 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

Copy file name to clipboardExpand all lines: components/cache/adapters/doctrine_adapter.rst
+23-8Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/filesystem_adapter.rst
+20-5Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/memcached_adapter.rst
+13-9Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/pdo_doctrine_dbal_adapter.rst
+22-4Lines 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

Copy file name to clipboardExpand all lines: components/cache/adapters/proxy_adapter.rst
+25-8Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.