8000 minor #11391 [Cache] Update cache for 4.2 (nicolas-grekas, Nyholm) · symfony/symfony-docs@c85eff1 · GitHub
[go: up one dir, main page]
Skip to content

Commit c85eff1

Browse files
javiereguiluzjaviereguiluz
committed
minor #11391 [Cache] Update cache for 4.2 (nicolas-grekas, Nyholm)
This PR was submitted for the master branch but it was merged into the 4.2 branch instead (closes #11391). Discussion ---------- [Cache] Update cache for 4.2 This will continue the work started in #10685 We need to document the CacheInterface from Contracts better. Commits ------- 1f819d5 added ref 46045bc fixes f59c055 updated link a5475f8 Added reference 6d51f93 minor 8b1d3d9 Adding examples of cache contracts e7b2bdf Update Cache component doc for 4.2
2 parents 50bbacc + 1f819d5 commit c85eff1

File tree

2 files changed

+93
-77
lines changed

2 files changed

+93
-77
lines changed

‎components/cache.rst

Lines changed: 90 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@
88
The Cache Component
99
===================
1010

11-
The Cache component provides an extended `PSR-6`_ implementation as well as
12-
a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications.
13-
It is designed for performance and resiliency, and ships with ready to use
14-
adapters for the most common caching backends, including proxies for adapting
15-
from/to `Doctrine Cache`_.
11 8000 +
The Cache component provides features covering simple to advanced caching needs.
12+
It natively implements `PSR-6`_ and the `Cache Contract`_ for greatest
13+
interoperability. It is designed for performance and resiliency, ships with
14+
ready to use adapters for the most common caching backends, including proxies for
15+
adapting from/to `Doctrine Cache`_ and `PSR-16`_. It enables tag-based invalidation
16+
and cache stampede protection.
1617

1718
Installation
1819
------------
@@ -23,112 +24,121 @@ Installation
2324
2425
.. include:: /components/require_autoload.rst.inc
2526

26-
Cache (PSR-6) Versus Simple Cache (PSR-16)
27-
------------------------------------------
27+
.. _cache-psr-6-versus-simple-cache-psr-16:
28+
29+
Cache Contracts versus PSR-6
30+
----------------------------
2831

2932
This component includes *two* different approaches to caching:
3033

3134
:ref:`PSR-6 Caching <cache-component-psr6-caching>`:
32-
A fully-featured cache system, which includes cache "pools", more advanced
33-
cache "items", and :ref:`cache tagging for invalidation <cache-component-tags>`.
35+
A generic cache system, which involves cache "pools" and cache "items".
36+
37+
:ref:`Cache Contracts <cache-component-contracts>`:
38+
A simple yet powerful way to store, fetch and remove values from a cache.
3439

35-
:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
36-
A simple way to store, fetch and remove items from a cache.
40+
.. tip::
3741

38-
Both methods support the *same* cache adapters and will give you very similar performance.
42+
Using the Cache Contracts approach is recommended: using it requires less
43+
code boilerplate and provides cache stampede protection by default.
3944

4045
.. tip::
4146

42-
The component also contains adapters to convert between PSR-6 and PSR-16 caches.
43-
See :doc:`/components/cache/psr6_psr16_adapters`.
47+
The component also contains adapters to convert between PSR-6, PSR-16 and
48+
Doctrine caches. See :doc:`/components/cache/psr6_psr16_adapters` and
49+
:doc:`/components/cache/adapters/doctrine_adapter`.
4450

45-
.. _cache-component-psr16-caching:
51+
.. _cache-component-contracts:
4652

47-
Simple Caching (PSR-16)
48-
-----------------------
53+
Cache Contracts
54+
---------------
4955

50-
This part of the component is an implementation of `PSR-16`_, which means that its
51-
basic API is the same as defined in the standard. First, create a cache object from
52-
one of the built-in cache classes. For example, to create a filesystem-based cache,
53-
instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
56+
All adapters supports the Cache Contract. It contains only two methods; ``get`` and
57+
``delete``. The first thing you need is to instantiate a cache adapter. The
58+
:class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache` is used in this example::
5459

55-
use Symfony\Component\Cache\Simple\FilesystemCache;
60+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
5661

57-
$cache = new FilesystemCache();
62+
$cache = new FilesystemAdapter();
5863

59-
Now you can create, retrieve, update and delete items using this object::
64+
Now you can retrieve and delete cached data using this object::
6065

61-
// save a new item in the cache
62-
$cache->set('stats.products_count', 4711);
66+
use Symfony\Contracts\Cache\ItemInterface;
6367

64-
// or set it with a custom ttl
65-
// $cache->set('stats.products_count', 4711, 3600);
68+
// The callable will only be executed on a cache miss.
69+
$value = $cache->get('my_cache_key', function (ItemInterface $item) {
70+
$item->expiresAfter(3600);
6671

67-
// retrieve the cache item
68-
if (!$cache->has('stats.products_count')) {
69-
// ... item does not exists in the cache
70-
}
72+
// ... do some HTTP request or heavy computations
73+
$computedValue = 'foobar';
7174

72-
// retrieve the value stored by the item
73-
$productsCount = $cache->get('stats.products_count');
75+
return $computedValue;
76+
});
7477

75-
// or specify a default value, if the key doesn't exist
76-
// $productsCount = $cache->get('stats.products_count', 100);
78+
echo $value; // 'foobar'
7779

78-
// remove the cache key
79-
$cache->delete('stats.products_count');
80+
// ... and to remove the cache key
81+
$cache->delete('my_cache_key');
8082

81-
// clear *all* cache keys
82-
$cache->clear();
83+
.. note::
8384

84-
You can also work with multiple items at once::
85+
Use tags to clear more than one key at the time. Read more at
86+
:doc:`/components/cache/cache_invalidation`.
8587

86-
$cache->setMultiple([
87-
'stats.products_count' => 4711,
88-
'stats.users_count' => 1356,
89-
]);
88+
The Cache Contracts also comes with built in `Stampede prevention`_. This will
89+
remove CPU spikes at the moments when the cache is cold. If an example application
90+
spends 5 seconds to compute data that is cached for 1 hour. This data is accessed
91+
10 times every second. This means that you mostly have cache hits and everything
92+
is fine. But after one hour, we get 10 new requests to a cold cache. So the data
93+
is computed again. The next second the same thing happens. So the data is computed
94+
about 50 times before the cache is warm again. This is where you need stampede
95+
prevention
9096

91-
$stats = $cache->getMultiple([
92-
'stats.products_count',
93-
'stats.users_count',
94-
]);
97+
The solution is to recompute the value before the cache expires. The algorithm
98+
randomly fakes a cache miss for one user while others still is served the cached
99+
value. The third parameter to ``CacheInterface::get`` is a beta value. The default
100+
is ``1.0`` which works well in practice. A higher value means earlier recompute.::
95101

96-
$cache->deleteMultiple([
97-
'stats.products_count',
98-
'stats.users_count',
99-
]);
102+
use Symfony\Contracts\Cache\ItemInterface;
100103

101-
Available Simple Cache (PSR-16) Classes
102-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
$beta = 1.0;
105+
$value = $cache->get('my_cache_key', function (ItemInterface $item) {
106+
$item->expiresAfter(3600);
107+
$item->tag(['tag_0', 'tag_1');
108+
109+
return '...';
110+
}, $beta);
111+
112+
Available Cache Adapters
113+
~~~~~~~~~~~~~~~~~~~~~~~~
103114

104115
The following cache adapters are available:
105116

106117
.. tip::
107118

108119
To find out more about each of these classes, you can read the
109-
:doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
110-
(PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
111-
each share constructor arguments and use-cases.
112-
113-
* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
114-
* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
115-
* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
116-
* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
117-
* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
118-
* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
119-
* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
120-
* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
121-
* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
122-
* :class:`Symfony\\Component\\Cache\\ F987 Simple\\PhpFilesCache`
123-
* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
124-
* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
120+
:doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page.
121+
122+
* :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter`
123+
* :class:`Symfony\\Component\\Cache\\Adapter\\ArrayAdapter`
124+
* :class:`Symfony\\Component\\Cache\\Adapter\\ChainAdapter`
125+
* :class:`Symfony\\Component\\Cache\\Adapter\\DoctrineAdapter`
126+
* :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`
127+
* :class:`Symfony\\Component\\Cache\\Adapter\\MemcachedAdapter`
128+
* :class:`Symfony\\Component\\Cache\\Adapter\\NullAdapter`
129+
* :class:`Symfony\\Component\\Cache\\Adapter\\PdoAdapter`
130+
* :class:`Symfony\\Component\\Cache\\Adapter\\PhpArrayAdapter`
131+
* :class:`Symfony\\Component\\Cache\\Adapter\\PhpFilesAdapter`
132+
* :class:`Symfony\\Component\\Cache\\Adapter\\RedisAdapter`
133+
* :class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter`
134+
* :class:`Symfony\\Component\\Cache\\Adapter\\TraceableAdapter`
125135

126136
.. _cache-component-psr6-caching:
127137

128-
More Advanced Caching (PSR-6)
129-
-----------------------------
138+
More Generic Caching (PSR-6)
139+
----------------------------
130140

131-
To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
141+
To use the more-generic, PSR-6 Caching abilities, you'll need to learn its key
132142
concepts:
133143

134144
**Item**
@@ -177,8 +187,10 @@ Now you can create, retrieve, update and delete items using this cache pool::
177187

178188
For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
179189

180-
Advanced Usage (PSR-6)
181-
----------------------
190+
.. _advanced-usage-psr-6:
191+
192+
Advanced Usage
193+
--------------
182194

183195
.. toctree::
184196
:glob:
@@ -187,5 +199,7 @@ Advanced Usage (PSR-6)
187199
cache/*
188200

189201
.. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
202+
.. _`Cache Contract`: https://github.com/symfony/contracts/blob/v1.0.0/Cache/CacheInterface.php
190203
.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
191204
.. _Doctrine Cache: https://www.doctrine-project.org/projects/cache.html
205+
.. _Stampede prevention: https://en.wikipedia.org/wiki/Cache_stampede

‎components/cache/psr6_psr16_adapters.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
Adapters For Interoperability between PSR-6 and PSR-16 Cache
77
============================================================
88

9-
Sometimes, you may have a Cache object that implements the :ref:`PSR-16 <cache-component-psr16-caching>`
9+
Sometimes, you may have a Cache object that implements the `PSR-16`_
1010
standard, but need to pass it to an object that expects a :ref:`PSR-6 <cache-component-psr6-caching>`
1111
cache adapter. Or, you might have the opposite situation. The cache component contains
1212
two classes for bidirectional interoperability between PSR-6 and PSR-16 caches.
@@ -84,3 +84,5 @@ this use-case::
8484

8585
// now use this wherever you want
8686
$githubApiClient = new GitHubApiClient($psr16Cache);
87+
88+
.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/

0 commit comments

Comments
 (0)
0