Skip to content

Commit 7893772

Browse files
weaverryanweaverryan
committed
feature #7417 Adding documentation about the simple cache PSR-16 implementation (weaverryan)
This PR was squashed before being merged into the master branch (closes #7417). Discussion ---------- Adding documentation about the simple cache PSR-16 implementation Hi guys! This covers #7409! Cheers! Commits ------- a6daf92 Adding documentation about the simple cache PSR-16 implementation
2 parents 5629491 + a6daf92 commit 7893772

File tree

3 files changed

+275
-17
lines changed

3 files changed

+275
-17
lines changed

‎components/cache.rst

Lines changed: 122 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,113 @@ 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 <cache-component-tags>`.
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+
.. tip::
43+
44+
The component also contains adapters to convert between PSR-6 and PSR-16 caches.
45+
See :doc:`/components/cache/psr6_psr16_adapters`.
46+
47+
.. _cache-component-psr16-caching:
48+
49+
Simple Caching (PSR-16)
50+
-----------------------
51+
52+
This part of the component is an implementation of `PSR-16`_, which means that its
53+
basic API is the same as defined in the standard. First, create a cache object from
54+
one of the built-in cache classes. For example, to create a filesystem-based cache,
55+
instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`::
56+
57+
use Symfony\Component\Cache\Simple\FilesystemCache;
58+
59+
$cache = new FilesystemCache();
60+
61+
Now you can create, retrieve, update and delete items using this object::
62+
63+
// save a new item in the cache
64+
$cache->set('stats.num_products', 4711);
65+
66+
// or set it with a custom ttl
67+
// $cache->set('stats.num_products', 4711, 3600);
68+
69+
// retrieve the cache item
70+
if (!$cache->has('stats.num_products')) {
71+
// ... item does not exists in the cache
72+
}
73+
74+
// retrieve the value stored by the item
75+
$numProducts = $cache->get('stats.num_products');
76+
77+
// or specify a default value, if the key doesn't exist
78+
// $numProducts = $cache->get('stats.num_products', 100);
79+
80+
// remove the cache key
81+
$cache->delete('stats.num_products');
82+
83+
// clear *all* cache keys
84+
$cache->clear();
85+
86+
You can also work with multiple items at once::
87+
88+
$cache->setMultiple(array(
89+
'stats.num_products' => 4711,
90+
'stats.num_users' => 1356,
91+
));
92+
93+
$stats = $cache->getMultiple(array(
94+
'stats.num_products',
95+
'stats.num_users',
96+
));
2697

27-
Before starting to use the Cache component, it's important that you learn the
28-
meaning of some key concepts:
98+
$cache->deleteMultiple(array(
99+
'stats.num_products',
100+
'stats.num_users',
101+
));
102+
103+
Available Simple Cache (PSR-16) Classes
104+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105+
106+
The following cache adapters are available:
107+
108+
.. tip::
109+
110+
To find out more about each of these classes, you can read the
111+
:doc:`PSR-6 Cache Pool </components/cache/cache_pools>` page. These "Simple"
112+
(PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but
113+
each share constructor arguments and use-cases.
114+
115+
* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache`
116+
* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache`
117+
* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache`
118+
* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache`
119+
* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`
120+
* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache`
121+
* :class:`Symfony\\Component\\Cache\\Simple\\NullCache`
122+
* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache`
123+
* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache`
124+
* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache`
125+
* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache`
126+
* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache`
127+
128+
.. _cache-component-psr6-caching:
129+
130+
More Advanced Caching (PSR-6)
131+
-----------------------------
132+
133+
To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key
134+
concepts:
29135

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

42-
Basic Usage
43-
-----------
148+
Basic Usage (PSR-6)
149+
-------------------
44150

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,
151+
This part of the component is an implementation of `PSR-6`_, which means that its
152+
basic API is the same as defined in the standard. Before starting to cache information,
47153
create the cache pool using any of the built-in adapters. For example, to create
48154
a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`::
49155

@@ -71,8 +177,10 @@ Now you can create, retrieve, update and delete items using this cache pool::
71177
// remove the cache item
72178
$cache->deleteItem('stats.num_products');
73179

74-
Advanced Usage
75-
--------------
180+
For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`.
181+
182+
Advanced Usage (PSR-6)
183+
----------------------
76184

77185
.. toctree::
78186
:glob:
@@ -81,4 +189,5 @@ Advanced Usage
81189
cache/*
82190

83191
.. _`PSR-6`: http://www.php-fig.org/psr/psr-6/
192+
.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/
84193
.. _Packagist: https://packagist.org/packages/symfony/cache

‎components/cache/cache_pools.rst

Lines changed: 67 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 and 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
@@ -107,8 +107,9 @@ This adapter stores the contents in the memory of a Redis server. Unlike the APC
107107
adapter, it's not limited to the shared memory of the current server, so you can
108108
store contents in a cluster of servers if needed.
109109

110-
It requires to have installed Redis and have created a connection that implements
111-
the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes::
110+
Before you start, make sure you have Redis running and have created a connection
111+
that implements the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis``
112+
classes::
112113

113114
use Symfony\Component\Cache\Adapter\RedisAdapter;
114115

@@ -127,6 +128,48 @@ helper allows creating a connection to a Redis server using a DSN configuration:
127128

128129
$redisConnection = RedisAdapter::createConnection('redis://localhost');
129130

131+
$cache = new RedisAdapter($redisConnection);
132+
133+
See the method's docblock for more options.
134+
135+
Memcached Cache Adapter
136+
~~~~~~~~~~~~~~~~~~~~~~~
137+
138+
This adapter stores the contents into a set of `Memcached`_ servers.
139+
140+
Before you start, make sure you have Memcached running and have created a
141+
:phpclass:`Memcached` object::
142+
143+
use Symfony\Component\Cache\Adapter\MemcachedAdapter;
144+
145+
$cache = new MemcachedAdapter(
146+
// the object that stores a valid connection to your Memcached servers
147+
\Memcached $client,
148+
// the string prefixed to the keys of the items stored in this cache
149+
$namespace = '',
150+
// in seconds; applied to cache items that don't define their own lifetime
151+
// 0 means to store the cache items indefinitely (i.e. until the Memcached memory is deleted)
152+
$defaultLifetime = 0
153+
);
154+
155+
The :method:`Symfony\\Component\\Cache\\Adapter\\Memcached::createConnection`
156+
helper allows creating a connection to a pool of Memcached server using a DSN configuration::
157+
158+
$memcachedClient = MemcachedAdapter::createConnection(
159+
'memcached://user:pass@localhost?weight=33',
160+
161+
// options, including username, password and Memcached::OPT_* options
162+
array('persistent_id' => '_products_cache')
163+
);
164+
165+
// alternate syntax: array notations for the servers
166+
$memcachedClient = MemcachedAdapter::createConnection(array(
167+
array('192.168.1.100', 11211, 33),
168+
array('192.168.1.101', 11211, 33)
169+
));
170+
171+
$cache = new MemcachedAdapter($memcachedClient);
172+
130173
See the method's docblock for more options.
131174

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

221+
Traceable Adapter
222+
~~~~~~~~~~~~~~~~~
223+
224+
This adapter wraps another adapter, and allows you to read a report of all of the
225+
"calls" made to the adapter, including how long actions took, cache hits, misses
226+
and more::
227+
228+
use Symfony\Component\Cache\Adapter\TraceableAdapter;
229+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
230+
231+
$fileCache = new FilesystemAdapter();
232+
233+
$cache = new TraceableAdapter($fileCache);
234+
235+
// work with the $cache adapter like normal
236+
237+
// returns an array of TraceableAdapterEvent describing the calls
238+
$events = $cache->getCalls();
239+
178240
Proxy Cache Adapter
179241
~~~~~~~~~~~~~~~~~~~
180242

@@ -333,3 +395,4 @@ when all items are successfully deleted)::
333395
$cacheIsEmpty = $cache->clear();
334396

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

‎components/cache/psr6_psr16_adapters.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. index::
2+
single: Cache
3+
single: Performance
4+
single: Components; Cache
5+
6+
Adapters For Interoperability between PSR-6 and PSR-16 Cache
7+
============================================================
8+
9+
Sometimes, you may have a Cache object that implements the :ref:`PSR-16 <cache-component-psr16-caching>`
10+
standard, but need to pass it to an object that expects a :ref:`PSR-6 <cache-component-psr6-caching>`
11+
cache adapter. Or, you might have the opposite situation. The cache component contains
12+
two classes for bidirectional interoperability between PSR-6 and PSR-16 caches.
13+
14+
Using a PSR-16 Cache Object as a PSR-6 Cache
15+
--------------------------------------------
16+
17+
Suppose you want to work with a class that requires a PSR-6 Cache pool object. For
18+
example::
19+
20+
use Psr\Cache\CacheItemPoolInterface;
21+
22+
// just a made-up class for the example
23+
class GitHubApiClient
24+
{
25+
// ...
26+
27+
// this requires a PSR-6 cache object
28+
public function __construct(CacheItemPoolInterface $cachePool)
29+
{
30+
// ...
31+
}
32+
}
33+
34+
But, you already have a PSR-16 cache object, and you'd like to pass this to the class
35+
instead. No problem! The Cache component provides the
36+
:class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter` class for exactly
37+
this use-case::
38+
39+
use Symfony\Component\Cache\Simple\FilesystemCache;
40+
use Symfony\Component\Cache\Adapter\SimpleCacheAdapter
41+
42+
// the PSR-16 cache object that you want to use
43+
$psr16Cache = new FilesystemCache();
44+
45+
// a PSR-6 cache that uses your cache internally!
46+
$psr6Cache = new SimpleCacheAdapter($psr16Cache);
47+
48+
// now use this wherever you want
49+
$githubApiClient = new GitHubApiClient($psr6Cache);
50+
51+
Using a PSR-6 Cache Object as a PSR-16 Cache
52+
--------------------------------------------
53+
54+
Suppose you want to work with a class that requires a PSR-16 Cache object. For
55+
example::
56+
57+
use Psr\SimpleCache\CacheInterface;
58+
59+
// just a made-up class for the example
60+
class GitHubApiClient
61+
{
62+
// ...
63+
64+
// this requires a PSR-16 cache object
65+
public function __construct(CacheInterface $cache)
66+
{
67+
// ...
68+
}
69+
}
70+
71+
But, you already have a PSR-6 cache pool object, and you'd like to pass this to
72+
the class instead. No problem! The Cache component provides the
73+
:class:`Symfony\\Component\\Cache\\Simple\\Psr6Cache` class for exactly
74+
this use-case::
75+
76+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
77+
use Symfony\Component\Cache\Simple\Psr6Cache;
78+
79+
// the PSR-6 cache object that you want to use
80+
$psr6Cache = new FilesystemAdapter();
81+
82+
// a PSR-16 cache that uses your cache internally!
83+
$psr16Cache = new Psr6Cache($psr6Cache);
84+
85+
// now use this wherever you want
86+
$githubApiClient = new GitHubApiClient($psr16Cache);

0 commit comments

Comments
 (0)