Skip to content

Commit 95e7978

Browse files
nicolas-grekasnicolas-grekas
committed
[Cache] Add chapter about invalidation, tags, etc.
1 parent b97d442 commit 95e7978

File tree

4 files changed

+136
-8
lines changed

4 files changed

+136
-8
lines changed

‎components/cache.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
The Cache Component
77
===================
88

9-
The Cache component provides a strict `PSR-6`_ implementation for adding
9+
The Cache component provides an extended `PSR-6`_ implementation for adding
1010
cache to your applications. It is designed to have a low overhead and it
1111
ships with ready to use adapters for the most common caching backends.
1212

@@ -42,7 +42,7 @@ meaning of some key concepts:
4242
Basic Usage
4343
-----------
4444

45-
This component is a strict implementation of `PSR-6`_, which means that the API
45+
This component is an implementation of `PSR-6`_, which means that its basic API
4646
is the same as defined in the standard. Before starting to cache information,
4747
create the cache pool using any of the built-in adapters. For example, to create
4848
a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::

‎components/cache/cache_invalidation.rst

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. index::
2+
single: Cache Invalidation
3+
single: Cache Tags
4+
single: Cache Namespaces
5+
6+
Cache Invalidation
7+
==================
8+
9+
Cache invalidation is the process of removing all cached items related to a
10+
change in the state of your model. The most basic kind of invalidation is direct
11+
items deletion. But when the state of a primary resource has spread accross
12+
several cached items, keeping them in sync can be difficult.
13+
14+
The Symfony Cache component provides three mechanisms to help solve this problem:
15+
16+
- tags based invalidation for managing data dependencies;
17+
- namespace based invalidation for context and sub-contexts dependend data;
18+
- expiration based invalidation for time related dependencies.
19+
20+
.. versionadded:: 3.2
21+
Tags and namespace based invalidation were introduced in Symfony 3.2.
22+
23+
Using Cache Tags
24+
----------------
25+
26+
To benefit from the tags based invalidation, your responsiblity is to attach the
27+
proper tags to each cached items. Each tag is a plain string identifier that you
28+
can use to trigger the removal of all items that had this tag attached to them.
29+
30+
To attach tags to cached items, you need to use the
31+
:method:`Symfony\\Component\\Cache\\CacheItem::tag` method that is implemented by
32+
cache items, as returned by cache adapters::
33+
34+
$item = $cache->getItem('cache_key');
35+
// [...]
36+
$item->tag('tag_1'); // you can add a single tag
37+
$item->tag(['tag_2', 'tag_3']); // or several at once
38+
$cache->save($item);
39+
40+
Let's assume ``$cache`` implements
41+
:class:`Symfony\\Component\\Cache\\TagAwareAdapterInterface`, you can then
42+
invalidate the previously cached item by calling e.g.::
43+
44+
// invalidate all items related to `tag_1`
45+
$cache->invalidateTags('tag_2');
46+
47+
// or invalidate all items related to `tag_1` or `tag_3`
48+
$cache->invalidateTags(['tag_1', 'tag_3']);
49+
50+
Of course when you know the cache key, it's better to call
51+
``$cache->deleteItem('cache_key');``, but this key is sometimes hard to track
52+
and this is where cache tags become useful.
53+
54+
Tag Aware Adapters
55+
~~~~~~~~~~~~~~~~~~
56+
57+
To store tags, you need to wrap a cache adapter with the
58+
:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class or implement
59+
:class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface` and its only
60+
:method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapterInterface::invalidateTags`
61+
method by yourself.
62+
63+
The :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` class implements
64+
instantaneous invalidation. It needs one or two cache adapters: the required one
65+
is used to store cached items; the second one is used to store tags and their
66+
invalidation version number (conceptually similar to their latest invalidation
67+
date). When only one adapter is used, items and tags are all stored in the same
68+
place. By using two adapters, you can e.g. store some big cached items on the
69+
filesystem or in the database, and keep tags in a Redis database to sync all your
70+
fronts and have very fast invalidation checks::
71+
72+
$cache = new TagAwareAdapter(
73+
new FilesystemAdapter(), // Adapter for cached items
74+
new RedisAdapter('redis://localhost') // Adapter for tags
75+
);
76+
77+
Using Cache Namespaces
78+
----------------------
79+
80+
By using adapters that implement the
81+
:method:`Symfony\\Component\\Cache\\Adapter\\ForkableAdapterInterface::fork`
82+
method from :class:`Symfony\\Component\\Cache\\Adapter\\ForkableAdapterInterface`,
83+
you can create context-dependent variations of your cached items::
84+
85+
$childCache = $parentCache->fork('child-namespace-name');
86+
$siblingCache = $parentCache->fork('sibling-namespace-name');
87+
$subChildCache = $childCache->fork('sub-child-namespace-name');
88+
89+
Clearing a parent adapter also clears all its forks::
90+
91+
$childCache->clear();
92+
// both $childCache and $subChildCache are now empty
93+
// but $parentCache and $siblingCache weren't affected
94+
95+
.. note::
96+
97+
Invalidating by tags affects all forks.
98+
99+
Using Cache Expiration
100+
----------------------
101+
102+
If your data is valid only for a limited period of time, you can specify their
103+
lifetime or their expiration date with the PSR-6 interface, as explained in the
104+
Cache Items article.

‎components/cache/cache_items.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ In the Cache component they are represented by the
1313
Cache Item Keys and Values
1414
--------------------------
1515

16-
The **key** of a cache item is a UTF-8 encoded string which acts as its
16+
The **key** of a cache item is a plain string which acts as its
1717
identifier, so it must be unique for each cache pool. You can freely choose the
1818
keys, but they should only contain letters (A-Z, a-z), numbers (0-9) and the
1919
``_`` and ``.`` symbols. Other common symbols (such as ``{``, ``}``, ``(``,

‎components/cache/cache_pools.rst

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Filesystem Cache Adapter
4141
~~~~~~~~~~~~~~~~~~~~~~~~
4242

4343
This adapter is useful when you want to improve the application performance but
44-
can't install tools like APC or Redis in the server. This adapter stores the
44+
can't install tools like APCu or Redis in the server. This adapter stores the
4545
contents as regular files in a set of directories on the local file system::
4646

4747
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
@@ -83,7 +83,7 @@ degrade performance significantly::
8383
Redis Cache Adapter
8484
~~~~~~~~~~~~~~~~~~~
8585

86-
This adapter stores the contents in the memory of the server. Unlike the APCu
86+
This adapter stores the contents in the memory of a Redis server. Unlike the APCu
8787
adapter, it's not limited to the shared memory of the current server, so you can
8888
store contents in a cluster of servers if needed.
8989

@@ -102,6 +102,33 @@ the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes::
102102
$defaultLifetime = 0
103103
);
104104

105+
The :method:`Symfony\\Component\\Cache\\Adapter\\RedisAdapter::createConnection`
106+
helper allows creating a connection to a Redis server using a DSN configuration::
107+
108+
$redisConnection = RedisAdapter::createConnection('redis://localhost');
109+
110+
See the method's docblock for more options.
111+
112+
PDO & Doctrine DBAL Cache Adapter
113+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114+
115+
This adapter stores the cached items a SQL database accessed through a PDO or a
116+
Doctrine DBAL connection::
117+
118+
use Symfony\Component\Cache\Adapter\PdoAdapter;
119+
120+
$cache = new PdoAdapter(
121+
// a PDO, a Doctrine DBAL connection or DSN for lazy connecting through PDO
122+
$databaseConnectionOrDSN,
123+
// the string prefixed to the keys of the items stored in this cache
124+
$namespace = '',
125+
// in seconds; applied to cache items that don't define their own lifetime
126+
// 0 means to store the cache items indefinitely (i.e. until the Redis memory is deleted)
127+
$defaultLifetime = 0,
128+
// an array of options for configuring the database connection
129+
$options = array()
130+
);
131+
105132
Chain Cache Adapter
106133
~~~~~~~~~~~~~~~~~~~
107134

@@ -141,9 +168,6 @@ that external cache and save them in the Symfony cache of your application::
141168
The adapter accepts two additional optional arguments: the namespace (``''`` by
142169
default) and the default lifetime (``0`` by default).
143170

144-
Another use case for this adapter is to get statistics and metrics about the
145-
cache hits (``getHits()``) and misses (``getMisses()``).
146-
147171
Doctrine Cache Adapter
148172
~~~~~~~~~~~~~~~~~~~~~~
149173

0 commit comments

Comments
 (0)