Skip to content

Commit f01db6d

Browse files
NyholmNyholm
committed
Starting on documentation for cache
1 parent dbb41f1 commit f01db6d

File tree

2 files changed

+196
-0
lines changed

2 files changed

+196
-0
lines changed

‎cache.rst

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
Cache
2+
=====
3+
4+
Using cache is a great way of making you application run quicker. The Symfony cache
5+
component is shipped with many adapters to different storages. Every adapter is
6+
developed for high performance.
7+
8+
Basic uses of the cache looks like this::
9+
10+
use Symfony\Contracts\Cache\ItemInterface;
11+
12+
// The callable will only be executed on a cache miss.
13+
$value = $pool->get('my_cache_key', function (ItemInterface $item) {
14+
$item->expiresAfter(3600);
15+
16+
// Do some HTTP request or heavy computations
17+
$computedValue = 'foobar';
18+
19+
return $computedValue;
20+
});
21+
22+
echo $value; // 'foobar'
23+
24+
$pool->delete('some_key');
25+
26+
27+
Symfony also supports PSR-6 and PSR-16 cache interfaces. You can read more about
28+
these at the :doc:`component documentation </components/cache>`.
29+
30+
31+
Configuring Cache with FrameworkBundle
32+
--------------------------------------
33+
34+
When configuring the the cache component there are a few concepts you should know
35+
of:
36+
37+
**Pool**
38+
This is a service that you will interact with. Each pool will always have
39+
its own namespace and cache items. There is never a conflict between pools.
40+
**Adapter**
41+
An adapter is a *template* that you use to create Pools.
42+
**Provider**
43+
A provider is the DSN connection to the actual storage.
44+
45+
There are two pools that are always enabled by default. They are ``cache.app`` and
46+
``cache.system``. The system cache is use for things like annotations, serializer,
47+
and validation. The ``cache.app`` can be used in your code. You can configure which
48+
adapter (template) they use by using the ``app`` and ``system`` key like:
49+
50+
.. code-block:: yaml
51+
52+
# config/packages/cache.yaml
53+
framework:
54+
cache:
55+
app: cache.adapter.filesystem
56+
system: cache.adapter.system
57+
58+
The Cache component comes with a series of adapters already created:
59+
60+
* :doc:`cache.adapter.apcu </components/cache/adapters/apcu-adapter>`
61+
* :doc:`cache.adapter.array </components/cache/adapters/array-cache-adapter>`
62+
* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine-adapter>`
63+
* :doc:`cache.adapter.filesystem </components/cache/adapters/filesystem-adapter>`
64+
* :doc:`cache.adapter.memcached </components/cache/adapters/memcached-adapter>`
65+
* :doc:`cache.adapter.pdo </components/cache/adapters/pdo-doctrine-dbal-adapter>`
66+
* :doc:`cache.adapter.redis </components/cache/adapters/redis-adapter>`
67+
* :doc:`PHPFileAdapter </components/cache/adapters/php-files-adapter>`
68+
* :doc:`PHPArrayAdapter </components/cache/adapters/php-array-adapter>`
69+
70+
* :doc:`ChainAdapter </components/cache/adapters/chain-adapter>`
71+
* :doc:`ProxyAdapter </components/cache/adapters/proxy-adapter>`
72+
* cache.adapter.psr6
73+
74+
* cache.adapter.system
75+
* NullAdapter
76+
77+
Some of these adapters could be configured via shortcuts. Using these shortcuts
78+
will create pool with service id of ``cache.[type]``
79+
80+
.. code-block:: yaml
81+
82+
# config/packages/cache.yaml
83+
framework:
84+
cache:
85+
directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
86+
87+
# service: cache.doctrine
88+
default_doctrine_provider: 'app.doctrine_cache'
89+
# service: cache.psr6
90+
default_psr6_provider: 'app.my_psr6_service'
91+
# service: cache.redis
92+
default_redis_provider: 'redis://localhost'
93+
# service: cache.memcached
94+
default_memcached_provider: 'memcached://localhost'
95+
# service: cache.pdo
96+
default_pdo_provider: 'doctrine.dbal.default_connection'
97+
98+
Creating Custom Pools
99+
---------------------
100+
101+
You can also create more customized pools. All you need is an adapter:
102+
103+
.. code-block:: yaml
104+
105+
# config/packages/cache.yaml
106+
framework:
107+
cache:
108+
default_memcached_provider: 'memcached://localhost'
109+
pools:
110+
my_cache_pool:
111+
adapter: cache.adapter.array
112+
cache.acme:
113+
adapter: cache.adapter.memcached
114+
cache.foobar:
115+
adapter: cache.adapter.memcached
116+
provider: 'memcached://user:password@example.com'
117+
118+
The configuration above will create 3 services: ``my_cache_pool``, ``cache.acme``
119+
and ``cache.foobar``. The ``my_cache_pool`` pool is using the ArrayAdapter
120+
and the other two are using the :doc:`MemcachedAdapter </components/cache/adapters/memcached-adapter>`.
121+
The ``cache.acme`` pool is using the Memcached server on localhost and ``cache.foobar``
122+
is using the Memcached server at example.com.
123+
124+
For advanced configurations it could sometimes be useful to use a pool as an adapter.
125+
126+
.. code-block:: yaml
127+
128+
# config/packages/cache.yaml
129+
framework:
130+
cache:
131+
pools:
132+
my_cache_pool:
133+
adapter: cache.adapter.memcached
134+
provider: 'memcached://user:password@example.com'
135+
cache.short_cache:
136+
adapter: my_cache_pool
137+
default_lifetime: 60
138+
cache.long_cache:
139+
adapter: my_cache_pool
140+
default_lifetime: 604800
141+
142+
Creating a Cache Chain
143+
----------------------
144+
145+
Different cache adapters has different strengths and weaknesses. Some might be really
146+
quick but small and some may be able to contain a lot of data but are quite slow.
147+
To get the best of both worlds you may use a chain of adapters. The idea is to
148+
first look at the quick adapter and then move on to slower adapters. In the worst
149+
case the value needs to be recalculated.
150+
151+
.. code-block:: yaml
152+
153+
# config/services.yaml
154+
services:
155+
app.my_cache_chain_adapter:
156+
class: Symfony\Component\Cache\Adapter\ChainAdapter
157+
arguments:
158+
- ['cache.adapter.array', 'cache.my_redis', 'cache.adapter.file']
159+
- 31536000 # One year
160+
161+
# config/packages/cache.yaml
162+
framework:
163+
cache:
164+
pools:
165+
my_cache_pool:
166+
adapter: app.my_cache_chain_adapter
167+
cache.my_redis:
168+
adapter: cache.adapter.redis
169+
provider: 'redis://user:password@example.com'
170+
171+
.. note::
172+
173+
In this configuration there is a ``cache.my_redis`` pool that is used as an
174+
adapter in the ``app.my_cache_chain_adapter``
175+
176+
177+
Clearing the Cache
178+
------------------
179+
180+
To clear the cache you can use the ``bin/console cache:pool:clear [pool]`` command.
181+
That will remove all the entries from your storage and you wil have to recalcuate
182+
all values. You can also group your pools into "cache clearers". There 3 cache clearer
183+
by default:
184+
185+
* cache.global_clearer
186+
* cache.system_clearer
187+
* cache.app_clearer
188+
189+
The global clearer clears all the cache in every pool. The system cache clearer
190+
is used in the ``bin/console cache:clear`` command. The app clearer is the default
191+
clearer.
192+
193+
.. code-block:: terminal
194+
195+
$ php bin/console cache:pool:clear cache.app_clearer

‎index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Topics
3232
:maxdepth: 1
3333

3434
bundles
35+
cache
3536
console
3637
doctrine
3738
deployment

0 commit comments

Comments
 (0)