Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 7893772

Browse filesBrowse 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
Copy full SHA for 7893772

File tree

Expand file treeCollapse file tree

3 files changed

+275
-17
lines changed
Filter options
Expand file treeCollapse file tree

3 files changed

+275
-17
lines changed

‎components/cache.rst

Copy file name to clipboardExpand all lines: components/cache.rst
+122-13Lines 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

Copy file name to clipboardExpand all lines: components/cache/cache_pools.rst
+67-4Lines 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

Copy file name to clipboard
+86Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.