8000 feature #7265 [Cache] Memcached Adapter Docs and Cache Pool Docs Refa… · symfony/symfony-docs@b8da0dd · GitHub
[go: up one dir, main page]
Skip to content

Commit b8da0dd

Browse files
xabbuhxabbuh
committed
feature #7265 [Cache] Memcached Adapter Docs and Cache Pool Docs Refactoring (robfrawley, javiereguiluz)
This PR was merged into the master branch. Discussion ---------- [Cache] Memcached Adapter Docs and Cache Pool Docs Refactoring Documentation for symfony/symfony#20863 and symfony/symfony#20858. PR symfony/symfony#20863 is still being written/finalized, so this is a WIP following that PR at this time. Resolves #7256. Commits ------- 7db929c corrected spelling/grammar c49d427 cleanup all cache adapter documentation, extend redis docs e3eff5b Reviewed the entire article d4292b7 refactor cache pool documentation and add memcached adapter docs
2 parents cbb1208 + 7db929c commit b8da0dd

File tree

14 files changed

+778
-295
lines changed

14 files changed

+778
-295
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: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.. index::
2+
single: Cache Pool
3+
single: APC Cache, APCu Cache
4+
5+
.. _apcu-adapter:
6+
7+
APCu Cache Adapter
8+
==================
9+
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.
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::
23+
24+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
25+
26+
$cache = new ApcuAdapter(
27+
28+
// a string prefixed to the keys of the items stored in this cache
29+
$namespace = '',
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)
34+
$defaultLifetime = 0,
35+
36+
// when set, all keys prefixed by $namespace can be invalidated by changing
37+
// this $version string
38+
$version = null
39+
);
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 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.
53+
54+
.. _`APCu extension`: https://pecl.php.net/package/APCu

‎components/cache/adapters/array_cache_adapter.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. index::
2+
single: Cache Pool
3+
single: Array Cache
4+
5+
Array Cache Adapter
6+
===================
7+
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::
15+
16+
use Symfony\Component\Cache\Adapter\ArrayAdapter;
17+
18+
$cache = new ArrayAdapter(
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)
23+
$defaultLifetime = 0,
24+
25+
// if ``true``, the values saved in the cache are serialized before storing them
26+
$storeSerialized = true
27+
);

‎components/cache/adapters/chain_adapter.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
.. index::
2+
single: Cache Pool
3+
single: Chain Cache
4+
5+
Chain Cache Adapter
6+
===================
7+
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::
14+
15+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
16+
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::
27+
28+
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
30+
previously missing.
31+
32+
The following example shows how to create a chain adapter instance using the fastest and
33+
slowest 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;
39+
40+
$cache = new ChainAdapter(array(
41+
new ApcuAdapter(),
42+
new FilesystemAdapter(),
43+
));

‎components/cache/adapters/doctrine_adapter.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. index::
2+
single: Cache Pool
3+
single: Doctrine Cache
4+
5+
.. _`doctrine-adapter`:
6+
7+
Doctrine Cache Adapter
8+
======================
9+
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::
16+
17+
use Doctrine\Common\Cache\CacheProvider;
18+
use Doctrine\Common\Cache\SQLite3Cache;
19+
use Symfony\Component\Cache\Adapter\DoctrineAdapter;
20+
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 = '',
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 database table is truncated or its rows are otherwise deleted)
34+
$defaultLifetime = 0
35+
);
36+
37+
.. _`Doctrine Cache`: https://github.com/doctrine/cache

‎components/cache/adapters/filesystem_adapter.rst

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. index::
2+
single: Cache Pool
3+
single: Filesystem Cache
4+
5+
Filesystem Cache Adapter
6+
========================
7+
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.
11+
12+
This adapter can optionally be provided a namespace, default cache lifetime, and
13+
directory path, as its first, second, and third parameters::
14+
15+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
16+
17+
$cache = new FilesystemAdapter(
18+
19+
// a string used as the subdirectory of the root cache directory, where cache
20+
// items will be stored
21+
$namespace = '',
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)
26+
$defaultLifetime = 0,
27+
28+
// the main cache directory (the application needs read-write permissions on it)
29+
// if none is specified, a directory is created inside the system temporary directory
30+
$directory = null
31+
);
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.

0 commit comments

Comments
 (0)
0