Skip to content

Commit d9fb6da

Browse files
weaverryanweaverryan
committed
Adding documentation about the simple cache PSR-16 implementation
1 parent ee31b7f commit d9fb6da

File tree

2 files changed

+182
-17
lines changed

2 files changed

+182
-17
lines changed

‎components/cache.rst‎

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

9-
The Cache component provides an extended `PSR-6`_ implementation for adding
10-
cache to your applications. It is designed to have a low overhead and it
11-
ships with ready to use adapters for the most common caching backends.
9+
The Cache component provides an extended `PSR-6`_ implementation as well as
10+
a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications.
11+
It is designed to have a low overhead and it ships with ready to use adapters
12+
for the most common caching backends.
1213

1314
.. versionadded:: 3.1
1415
The Cache component was introduced in Symfony 3.1.
1516

17+
.. versionadded:: 3.3
18+
The PSR-16 "Simple Cache" implementation was introduced in Symfony 3.3.
19+
1620
Installation
1721
------------
1822

@@ -21,11 +25,27 @@ You can install the component in 2 different ways:
2125
* :doc:`Install it via Composer </components/using_components>` (``symfony/cache`` on `Packagist`_);
2226
* Use the official Git repository (https://github.com/symfony/cache).
2327

24-
Key Concepts
25-
------------
28+
Cache (PSR-6) Versus Simple Cache (PSR-16)
29+
------------------------------------------
30+
31+
This component includes *two* different approaches to caching:
32+
33+
:ref:`PSR-6 Caching <cache-component-psr6-caching>`:
34+
A fully-featured cache system, which includes cache "pools", more advanced
35+
cache "items", and :ref:`cache tagging for invalidation <TODO>`.
36+
37+
:ref:`PSR-16 Simple Caching <cache-component-psr16-caching>`:
38+
A simple way to store, fetch and remove items from a cache.
39+
40+
Both methods support the *same* cache adapters and will give you very similar performance.
41+
42+
.. _cache-component-psr6-caching:
2643

27-
Before starting to use the Cache component, it's important that you learn the
28-
meaning of some key concepts:
44+
More Advanced Caching (PSR-6)
45+
-----------------------------
46+
47+
To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
48+
concepts:
2949

3050
**Item**
3151
A single unit of information stored as a key/value pair, where the key is
@@ -39,11 +59,11 @@ meaning of some key concepts:
3959
filesystem, in a database, etc. The component provides several ready to use
4060
adapters for common caching backends (Redis, APCu, etc.)
4161

42-
Basic Usage
43-
-----------
62+
Basic Usage (PSR-6)
63+
-------------------
4464

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

@@ -71,14 +91,98 @@ Now you can create, retrieve, update and delete items using this cache pool::
7191
// remove the cache item
7292
$cache->deleteItem('stats.num_products');
7393

74-
Advanced Usage
75-
--------------
94+
For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
95+
96+
Advanced Usage (PSR-6)
97+
----------------------
7698

7799
.. toctree::
78100
:glob:
79101
:maxdepth: 1
80102

81103
cache/*
82104

105+
.. _cache-component-psr16-caching:
106+
107+
Simple Caching (PSR-16)
108+
-----------------------
109+
110+
This part of the component is an implementation of `PSR-16`_, which means that its
111+
basic API is the same as defined in the standard. First, create a cache object from
112+
one of the built-in cache clases. For example, to create a filesystem-based cache,
113+
instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
114+
115+
use Symfony\Component\Cache\Simple\FilesystemCache;
116+
117+
$cache = new FilesystemCache();
118+
119+
Now you can create, retrieve, update and delete items using this object::
120+
121+
// save a new item in the cache
122+
$cache->set('stats.num_products', 4711);
123+
124+
// or set it with a custom ttl
125+
// $cache->set('stats.num_products', 4711, 3600);
126+
127+
// retrieve the cache item
128+
if (!$cache->has('stats.num_products')) {
129+
// ... item does not exists in the cache
130+
}
131+
132+
// retrieve the value stored by the item
133+
$numProducts = $cache->get('stats.num_products');
134+
135+
// or specify a default value, if the key doesn't exist
136+
// $numProducts = $cache->get('stats.num_products', 100);
137+
138+
// remove the cache key
139+
$cache->deleteItem('stats.num_products');
140+
141+
// clear *all* cache keys
142+
$cache->clear();
143+
144+
You can also work with multiple items at once::
145+
146+
$cache->setMultiple([
147+
'stats.num_products' => 4711,
148+
'stats.num_users' => 1356,
149+
]);
150+
151+
$stats = $cache->getMultiple([
152+
'stats.num_products',
153+
'stats.num_users',
154+
]);
155+
156+
$cache->deleteMultiple([
157+
'stats.num_products',
158+
'stats.num_users',
159+
]);
160+
161+
Available Simple Cache (PSR-16) Classes
162+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163+
164+
The following cache adapters are available:
165+
166+
.. tip::
167+
168+
To find out more about each of these classes, you can read th
169+
:doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
170+
(PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
171+
each share constructor arguments and use-cases.
172+
173+
* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
174+
* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
175+
* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
176+
* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
177+
* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
178+
* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
179+
* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
180+
* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
181+
* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
182+
* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache`
183+
* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
184+
* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
185+
83186
.. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
187+
.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
84188
.. _Packagist: https://packagist.org/packages/symfony/cache

‎components/cache/cache_pools.rst‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
single: Redis Cache
66
single: PDO Cache, Doctrine DBAL Cache
77

8-
Cache Pools
9-
===========
8+
Cache Pools & Supported Adapters
9+
================================
1010

1111
Cache Pools are the logical repositories of cache items. They perform all the
1212
common operations on items, such as saving them or looking for them. Cache pools
@@ -88,8 +88,9 @@ This adapter stores the contents in the memory of a Redis server. Unlike the APC
8888
adapter, it's not limited to the shared memory of the current server, so you can
8989
store contents in a cluster of servers if needed.
9090

91-
It requires to have installed Redis and have created a connection that implements
92-
the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes::
91+
Before you start, make sure you have Redis running and have created a connection
92+
that implements the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis``
93+
classes::
9394

9495
use Symfony\Component\Cache\Adapter\RedisAdapter;
9596

@@ -108,6 +109,46 @@ helper allows creating a connection to a Redis server using a DSN configuration:
108109

109110
$redisConnection = RedisAdapter::createConnection('redis://localhost');
110111

112+
$cache = new RedisAdapter($redisConnection);
113+
114+
See the method's docblock for more options.
115+
116+
Memcached Cache Adapter
117+
~~~~~~~~~~~~~~~~~~~~~~~
118+
119+
This adapter stores the contents into a set of `Memcached`_ servers.
120+
121+
Before you start, make sure you have Memcached running and have created a
122+
:phpclass:`Memcached` object::
123+
124+
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
125+
126+
$cache = new MemcachedAdapter(
127+
// the object that stores a valid connection to your Memcached servers
128+
\Memcached $client,
129+
// the string prefixed to the keys of the items stored in this cache
130+
$namespace = '',
131+
// in seconds; applied to cache items that don't define their own lifetime
132+
// 0 means to store the cache items indefinitely (i.e. until the Memcached memory is deleted)
133+
$defaultLifetime = 0
134+
);
135+
136+
The :method:`Symfony\\Component\\Cache\\Adapter\\Memcached::createConnection`
137+
helper allows creating a connection to a pool of Memcached server using a DSN configuration::
138+
139+
$memcachedClient = MemcachedAdapter::createConnection(
140+
'memcached://user:pass@localhost?weight=33',
141+
142+
// options, including username, password and Memcached::OPT_* options
143+
['persistent_id' => '_products_cache']
144+
);
145+
$memcachedClient = MemcachedAdapter::createConnection([
146+
array('192.168.1.100', 11211, 33),
147+
array('192.168.1.101', 11211, 33)
148+
]);
149+
150+
$cache = new MemcachedAdapter($memcachedClient);
151+
111152
See the method's docblock for more options.
112153

113154
PDO & Doctrine DBAL Cache Adapter
@@ -156,6 +197,25 @@ where it was missing. Since it's not possible to know the expiry date and time
156197
of a cache item, the second optional argument of ``ChainAdapter`` is the default
157198
lifetime applied to those cache items (by default it's ``0``).
158199

200+
Traceable Adapter
201+
~~~~~~~~~~~~~~~~~
202+
203+
This adapter wraps another adapter, and allows you to read a report of all of the
204+
"calls" made to the adapter, including how long actions took, cache hits, misses
205+
and more::
206+
207+
use Symfony\Component\Cache\Adapter\TraceableAdapter;
208+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
209+
210+
$fileCache = new FilesystemAdapter();
211+
212+
$cache = new TraceableAdapter(array($fileCache));
213+
214+
// work with the $cache adapter like normal
215+
216+
// returns an array of TraceableAdapterEvent describing the calls
217+
$events = $cache->getCalls();
218+
159219
Proxy Cache Adapter
160220
~~~~~~~~~~~~~~~~~~~
161221

@@ -279,3 +339,4 @@ when all items are successfully deleted)::
279339
$cacheIsEmpty = $cache->clear();
280340

281341
.. _`Doctrine Cache`: https://github.com/doctrine/cache
342+
.. _`Memcached`: http://php.net/manual/en/book.memcached.php

0 commit comments

Comments
 (0)