Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Reformatting to look more like the PSR-1 and PSR-2 docs.

  • Loading branch information...
commit bda016793c4f2d04a0d949683430e804e5a4e426 1 parent 4234316
Evert Pot authored

Showing 1 changed file with 181 additions and 172 deletions. Show diff stats Hide diff stats

  1. +181 172 proposed/objectcache.md
353 proposed/objectcache.md
Source Rendered
... ... @@ -1,4 +1,5 @@
1   -## Introduction
  1 +Cache Interface
  2 +===============
2 3
3 4 Many PHP frameworks define a PHP persistant object cache with various features.
4 5 An object cache is something that may be useful in many parts of an
@@ -20,60 +21,65 @@ they wish to support.
20 21
21 22 To fix this, this document proposes a very simple standard interface.
22 23
23   -## The base interface
24   -
25   - namespace PSR\Cache;
26   -
27   - interface Base {
28   -
29   - /**
30   - * Stores a new value in the cache.
31   - *
32   - * The key must be provided as a string, the value may be any
33   - * serializable PHP value.
34   - *
35   - * Use the $ttl argument to specify how long the cache is valid for.
36   - * The time-to-live is specified in seconds.
37   - *
38   - * If $ttl is not specified, the implementation may choose a default.
39   - *
40   - * @param string $key
41   - * @param mixed $value
42   - * @param int $ttl
43   - * @return void
44   - */
45   - function set($key, $value, $ttl = null);
46   -
47   - /**
48   - * Fetches an object from the cache.
49   - *
50   - * If the object did not exist, this method must return null.
51   - *
52   - * @param string $key
53   - * @return mixed
54   - */
55   - function get($key);
56   -
57   - /**
58   - * Deletes an item from the cache.
59   - *
60   - * This method must succeed, even if the item did not exist.
61   - *
62   - * @param string $key
63   - * @return void
64   - */
65   - function delete($key);
66   -
67   -
68   - /**
69   - * Check if the key exists in the cache.
70   - *
71   - * @param string $key
72   - * @return boolean
73   - */
74   - function exists($key);
75   -
76   - }
  24 +1. The base interface
  25 +---------------------
  26 +
  27 +```php
  28 +namespace PSR\Cache;
  29 +
  30 +interface Base {
  31 +
  32 + /**
  33 + * Stores a new value in the cache.
  34 + *
  35 + * The key must be provided as a string, the value may be any
  36 + * serializable PHP value.
  37 + *
  38 + * Use the $ttl argument to specify how long the cache is valid for.
  39 + * The time-to-live is specified in seconds.
  40 + *
  41 + * If $ttl is not specified, the implementation may choose a default.
  42 + * The $ttl argument should be considered a 'suggestion'. The
  43 + * implementation may ignore it.
  44 + *
  45 + * @param string $key
  46 + * @param mixed $value
  47 + * @param int $ttl
  48 + * @return void
  49 + */
  50 + function set($key, $value, $ttl = null);
  51 +
  52 + /**
  53 + * Fetches an object from the cache.
  54 + *
  55 + * If the object did not exist, this method must return null.
  56 + *
  57 + * @param string $key
  58 + * @return mixed
  59 + */
  60 + function get($key);
  61 +
  62 + /**
  63 + * Deletes an item from the cache.
  64 + *
  65 + * This method must succeed, even if the item did not exist.
  66 + *
  67 + * @param string $key
  68 + * @return void
  69 + */
  70 + function delete($key);
  71 +
  72 +
  73 + /**
  74 + * Check if the key exists in the cache.
  75 + *
  76 + * @param string $key
  77 + * @return boolean
  78 + */
  79 + function exists($key);
  80 +
  81 +}
  82 +```
77 83
78 84 ## Bulk operations
79 85
@@ -82,135 +88,142 @@ benefit is that requests can be pipelined, thus reducing latency.
82 88
83 89 For these cases the Multiple interface may be implemented.
84 90
85   - namespace PSR\Cache;
86   -
87   - interface Multiple extends Base {
88   -
89   - /**
90   - * Stores multiple items in the cache at once.
91   - *
92   - * The items must be provided as an associative array.
93   - *
94   - * @param array $items
95   - * @param int $ttl
96   - * @return void
97   - */
98   - function setMultiple(array $items, $ttl = null);
99   -
100   - /**
101   - * Fetches multiple items from the cache.
102   - *
103   - * The returned structure must be an associative array. If items were
104   - * not found in the cache, they should not be included in the array.
105   - *
106   - * This means that if none of the items are found, this method must
107   - * return an empty array.
108   - *
109   - * @param string $keys
110   - * @return array
111   - */
112   - function getMultiple($keys);
113   -
114   - /**
115   - * Deletes multiple items from the cache at once.
116   - *
117   - * @param array $key
118   - * @return void
119   - */
120   - function deleteMultiple($keys);
121   -
122   - /**
123   - * Check for multiple items if they appear in the cache.
124   - *
125   - * All items must be returned as an array. And each must array value
126   - * must either be set to true, or false.
127   - *
128   - * @param array $keys
129   - * @return array
130   - */
131   - function existsMultiple($keys);
132   -
133   - }
  91 +```php
  92 +namespace PSR\Cache;
  93 +
  94 +interface Multiple extends Base {
  95 +
  96 + /**
  97 + * Stores multiple items in the cache at once.
  98 + *
  99 + * The items must be provided as an associative array.
  100 + *
  101 + * @param array $items
  102 + * @param int $ttl
  103 + * @return void
  104 + */
  105 + function setMultiple(array $items, $ttl = null);
  106 +
  107 + /**
  108 + * Fetches multiple items from the cache.
  109 + *
  110 + * The returned structure must be an associative array. If items were
  111 + * not found in the cache, they should not be included in the array.
  112 + *
  113 + * This means that if none of the items are found, this method must
  114 + * return an empty array.
  115 + *
  116 + * @param string $keys
  117 + * @return array
  118 + */
  119 + function getMultiple($keys);
  120 +
  121 + /**
  122 + * Deletes multiple items from the cache at once.
  123 + *
  124 + * @param array $key
  125 + * @return void
  126 + */
  127 + function deleteMultiple($keys);
  128 +
  129 + /**
  130 + * Check for multiple items if they appear in the cache.
  131 + *
  132 + * All items must be returned as an array. And each must array value
  133 + * must either be set to true, or false.
  134 + *
  135 + * @param array $keys
  136 + * @return array
  137 + */
  138 + function existsMultiple($keys);
  139 +
  140 +}
  141 +```
134 142
135 143 If the backend does not natively implement bulk operations, it can still
136 144 be easily emulated. The following trait could be used as an example to emulate
137   -this. Note that this is only an example, and should not be considered as part
138   -of the specification.
139   -
140   - trait EmulateMultiple {
141   -
142   - /**
143   - * Stores multiple items in the cache at once.
144   - *
145   - * The items must be provided as an associative array.
146   - *
147   - * @param array $items
148   - * @param int $ttl
149   - * @return void
150   - */
151   - public function setMultiple(array $items, $ttl = null) {
152   -
153   - foreach($items as $key=>$value) {
154   - $this->set($key, $value, $ttl);
155   - }
  145 +this.
156 146
157   - }
  147 +**Note that this trait is strictly an example, and MUST NOT be considered as
  148 +part of the standard.**
158 149
159   - /**
160   - * Fetches multiple items from the cache.
161   - *
162   - * The returned structure must be an associative array. If items were
163   - * not found in the cache, they should not be included in the array.
164   - *
165   - * This means that if none of the items are found, this method must
166   - * return an empty array.
167   - *
168   - * @param string $keys
169   - * @return array
170   - */
171   - public function getMultiple($keys) {
172   -
173   - return array_map(
174   - array($this, 'get'),
175   - $keys
176   - );
  150 +```php
177 151
  152 +trait EmulateMultiple {
  153 +
  154 + /**
  155 + * Stores multiple items in the cache at once.
  156 + *
  157 + * The items must be provided as an associative array.
  158 + *
  159 + * @param array $items
  160 + * @param int $ttl
  161 + * @return void
  162 + */
  163 + public function setMultiple(array $items, $ttl = null) {
  164 +
  165 + foreach($items as $key=>$value) {
  166 + $this->set($key, $value, $ttl);
178 167 }
179 168
180   - /**
181   - * Deletes multiple items from the cache at once.
182   - *
183   - * @param array $key
184   - * @return void
185   - */
186   - public function deleteMultiple($keys) {
  169 + }
187 170
188   - foreach($keys as $key) {
189   - $this->delete($key);
190   - }
  171 + /**
  172 + * Fetches multiple items from the cache.
  173 + *
  174 + * The returned structure must be an associative array. If items were
  175 + * not found in the cache, they should not be included in the array.
  176 + *
  177 + * This means that if none of the items are found, this method must
  178 + * return an empty array.
  179 + *
  180 + * @param string $keys
  181 + * @return array
  182 + */
  183 + public function getMultiple($keys) {
  184 +
  185 + return array_map(
  186 + array($this, 'get'),
  187 + $keys
  188 + );
191 189
192   - }
  190 + }
193 191
194   - /**
195   - * Check for multiple items if they appear in the cache.
196   - *
197   - * All items must be returned as an array. And each must array value
198   - * must either be set to true, or false.
199   - *
200   - * @param array $keys
201   - * @return array
202   - */
203   - public function existsMultiple($keys) {
204   -
205   - return array_map(
206   - array($this, 'exists'),
207   - $keys
208   - );
  192 + /**
  193 + * Deletes multiple items from the cache at once.
  194 + *
  195 + * @param array $key
  196 + * @return void
  197 + */
  198 + public function deleteMultiple($keys) {
209 199
  200 + foreach($keys as $key) {
  201 + $this->delete($key);
210 202 }
211 203
212 204 }
213 205
  206 + /**
  207 + * Check for multiple items if they appear in the cache.
  208 + *
  209 + * All items must be returned as an array. And each must array value
  210 + * must either be set to true, or false.
  211 + *
  212 + * @param array $keys
  213 + * @return array
  214 + */
  215 + public function existsMultiple($keys) {
  216 +
  217 + return array_map(
  218 + array($this, 'exists'),
  219 + $keys
  220 + );
  221 +
  222 + }
  223 +
  224 +}
  225 +```
  226 +
214 227 ## Notes
215 228
216 229 * This document does not define how to handle error conditions, such as the
@@ -218,7 +231,3 @@ of the specification.
218 231 * This document does not define what constitutes valid keys. Backends may have
219 232 restrictions around this. It is recommended for the calling code to use
220 233 sane keys, and possibly run a hash function if needed.
221   -
222   -## Todo
223   -
224   -

0 comments on commit bda0167

Please sign in to comment.
Something went wrong with that request. Please try again.