Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\Cache;
|
Chris@0
|
4
|
Chris@0
|
5 /**
|
Chris@0
|
6 * Defines an interface for cache implementations.
|
Chris@0
|
7 *
|
Chris@0
|
8 * All cache implementations have to implement this interface.
|
Chris@0
|
9 * Drupal\Core\Cache\DatabaseBackend provides the default implementation, which
|
Chris@0
|
10 * can be consulted as an example.
|
Chris@0
|
11 *
|
Chris@17
|
12 * The cache identifiers are case sensitive.
|
Chris@0
|
13 *
|
Chris@0
|
14 * @ingroup cache
|
Chris@0
|
15 */
|
Chris@0
|
16 interface CacheBackendInterface {
|
Chris@0
|
17
|
Chris@0
|
18 /**
|
Chris@0
|
19 * Indicates that the item should never be removed unless explicitly deleted.
|
Chris@0
|
20 */
|
Chris@0
|
21 const CACHE_PERMANENT = -1;
|
Chris@0
|
22
|
Chris@0
|
23 /**
|
Chris@0
|
24 * Returns data from the persistent cache.
|
Chris@0
|
25 *
|
Chris@0
|
26 * @param string $cid
|
Chris@0
|
27 * The cache ID of the data to retrieve.
|
Chris@0
|
28 * @param bool $allow_invalid
|
Chris@0
|
29 * (optional) If TRUE, a cache item may be returned even if it is expired or
|
Chris@0
|
30 * has been invalidated. Such items may sometimes be preferred, if the
|
Chris@0
|
31 * alternative is recalculating the value stored in the cache, especially
|
Chris@0
|
32 * if another concurrent request is already recalculating the same value.
|
Chris@0
|
33 * The "valid" property of the returned object indicates whether the item is
|
Chris@0
|
34 * valid or not. Defaults to FALSE.
|
Chris@0
|
35 *
|
Chris@0
|
36 * @return object|false
|
Chris@0
|
37 * The cache item or FALSE on failure.
|
Chris@0
|
38 *
|
Chris@0
|
39 * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
|
Chris@0
|
40 */
|
Chris@0
|
41 public function get($cid, $allow_invalid = FALSE);
|
Chris@0
|
42
|
Chris@0
|
43 /**
|
Chris@0
|
44 * Returns data from the persistent cache when given an array of cache IDs.
|
Chris@0
|
45 *
|
Chris@0
|
46 * @param array $cids
|
Chris@0
|
47 * An array of cache IDs for the data to retrieve. This is passed by
|
Chris@0
|
48 * reference, and will have the IDs successfully returned from cache
|
Chris@0
|
49 * removed.
|
Chris@0
|
50 * @param bool $allow_invalid
|
Chris@0
|
51 * (optional) If TRUE, cache items may be returned even if they have expired
|
Chris@0
|
52 * or been invalidated. Such items may sometimes be preferred, if the
|
Chris@0
|
53 * alternative is recalculating the value stored in the cache, especially
|
Chris@0
|
54 * if another concurrent thread is already recalculating the same value. The
|
Chris@0
|
55 * "valid" property of the returned objects indicates whether the items are
|
Chris@0
|
56 * valid or not. Defaults to FALSE.
|
Chris@0
|
57 *
|
Chris@0
|
58 * @return array
|
Chris@0
|
59 * An array of cache item objects indexed by cache ID.
|
Chris@0
|
60 *
|
Chris@0
|
61 * @see \Drupal\Core\Cache\CacheBackendInterface::get()
|
Chris@0
|
62 */
|
Chris@0
|
63 public function getMultiple(&$cids, $allow_invalid = FALSE);
|
Chris@0
|
64
|
Chris@0
|
65 /**
|
Chris@0
|
66 * Stores data in the persistent cache.
|
Chris@0
|
67 *
|
Chris@0
|
68 * Core cache implementations set the created time on cache item with
|
Chris@0
|
69 * microtime(TRUE) rather than REQUEST_TIME_FLOAT, because the created time
|
Chris@0
|
70 * of cache items should match when they are created, not when the request
|
Chris@0
|
71 * started. Apart from being more accurate, this increases the chance an
|
Chris@0
|
72 * item will legitimately be considered valid.
|
Chris@0
|
73 *
|
Chris@0
|
74 * @param string $cid
|
Chris@0
|
75 * The cache ID of the data to store.
|
Chris@0
|
76 * @param mixed $data
|
Chris@0
|
77 * The data to store in the cache.
|
Chris@0
|
78 * Some storage engines only allow objects up to a maximum of 1MB in size to
|
Chris@0
|
79 * be stored by default. When caching large arrays or similar, take care to
|
Chris@0
|
80 * ensure $data does not exceed this size.
|
Chris@0
|
81 * @param int $expire
|
Chris@0
|
82 * One of the following values:
|
Chris@0
|
83 * - CacheBackendInterface::CACHE_PERMANENT: Indicates that the item should
|
Chris@0
|
84 * not be removed unless it is deleted explicitly.
|
Chris@0
|
85 * - A Unix timestamp: Indicates that the item will be considered invalid
|
Chris@0
|
86 * after this time, i.e. it will not be returned by get() unless
|
Chris@0
|
87 * $allow_invalid has been set to TRUE. When the item has expired, it may
|
Chris@0
|
88 * be permanently deleted by the garbage collector at any time.
|
Chris@0
|
89 * @param array $tags
|
Chris@0
|
90 * An array of tags to be stored with the cache item. These should normally
|
Chris@0
|
91 * identify objects used to build the cache item, which should trigger
|
Chris@0
|
92 * cache invalidation when updated. For example if a cached item represents
|
Chris@0
|
93 * a node, both the node ID and the author's user ID might be passed in as
|
Chris@0
|
94 * tags. For example ['node:123', 'node:456', 'user:789'].
|
Chris@0
|
95 *
|
Chris@0
|
96 * @see \Drupal\Core\Cache\CacheBackendInterface::get()
|
Chris@0
|
97 * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
|
Chris@0
|
98 */
|
Chris@0
|
99 public function set($cid, $data, $expire = Cache::PERMANENT, array $tags = []);
|
Chris@0
|
100
|
Chris@0
|
101 /**
|
Chris@0
|
102 * Store multiple items in the persistent cache.
|
Chris@0
|
103 *
|
Chris@0
|
104 * @param array $items
|
Chris@0
|
105 * An array of cache items, keyed by cid. In the form:
|
Chris@0
|
106 * @code
|
Chris@0
|
107 * $items = array(
|
Chris@0
|
108 * $cid => array(
|
Chris@0
|
109 * // Required, will be automatically serialized if not a string.
|
Chris@0
|
110 * 'data' => $data,
|
Chris@0
|
111 * // Optional, defaults to CacheBackendInterface::CACHE_PERMANENT.
|
Chris@0
|
112 * 'expire' => CacheBackendInterface::CACHE_PERMANENT,
|
Chris@0
|
113 * // (optional) The cache tags for this item, see CacheBackendInterface::set().
|
Chris@0
|
114 * 'tags' => array(),
|
Chris@0
|
115 * ),
|
Chris@0
|
116 * );
|
Chris@0
|
117 * @endcode
|
Chris@0
|
118 */
|
Chris@0
|
119 public function setMultiple(array $items);
|
Chris@0
|
120
|
Chris@0
|
121 /**
|
Chris@0
|
122 * Deletes an item from the cache.
|
Chris@0
|
123 *
|
Chris@0
|
124 * If the cache item is being deleted because it is no longer "fresh", you may
|
Chris@0
|
125 * consider using invalidate() instead. This allows callers to retrieve the
|
Chris@0
|
126 * invalid item by calling get() with $allow_invalid set to TRUE. In some cases
|
Chris@0
|
127 * an invalid item may be acceptable rather than having to rebuild the cache.
|
Chris@0
|
128 *
|
Chris@0
|
129 * @param string $cid
|
Chris@0
|
130 * The cache ID to delete.
|
Chris@0
|
131 *
|
Chris@0
|
132 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
|
Chris@0
|
133 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
|
Chris@0
|
134 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
|
Chris@0
|
135 */
|
Chris@0
|
136 public function delete($cid);
|
Chris@0
|
137
|
Chris@0
|
138 /**
|
Chris@0
|
139 * Deletes multiple items from the cache.
|
Chris@0
|
140 *
|
Chris@0
|
141 * If the cache items are being deleted because they are no longer "fresh",
|
Chris@0
|
142 * you may consider using invalidateMultiple() instead. This allows callers to
|
Chris@0
|
143 * retrieve the invalid items by calling get() with $allow_invalid set to TRUE.
|
Chris@0
|
144 * In some cases an invalid item may be acceptable rather than having to
|
Chris@0
|
145 * rebuild the cache.
|
Chris@0
|
146 *
|
Chris@0
|
147 * @param array $cids
|
Chris@0
|
148 * An array of cache IDs to delete.
|
Chris@0
|
149 *
|
Chris@0
|
150 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
|
Chris@0
|
151 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
|
Chris@0
|
152 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
|
Chris@0
|
153 */
|
Chris@0
|
154 public function deleteMultiple(array $cids);
|
Chris@0
|
155
|
Chris@0
|
156 /**
|
Chris@0
|
157 * Deletes all cache items in a bin.
|
Chris@0
|
158 *
|
Chris@0
|
159 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
|
Chris@0
|
160 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
|
Chris@0
|
161 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
|
Chris@0
|
162 */
|
Chris@0
|
163 public function deleteAll();
|
Chris@0
|
164
|
Chris@0
|
165 /**
|
Chris@0
|
166 * Marks a cache item as invalid.
|
Chris@0
|
167 *
|
Chris@0
|
168 * Invalid items may be returned in later calls to get(), if the $allow_invalid
|
Chris@0
|
169 * argument is TRUE.
|
Chris@0
|
170 *
|
Chris@0
|
171 * @param string $cid
|
Chris@0
|
172 * The cache ID to invalidate.
|
Chris@0
|
173 *
|
Chris@0
|
174 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
|
Chris@0
|
175 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
|
Chris@0
|
176 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
|
Chris@0
|
177 */
|
Chris@0
|
178 public function invalidate($cid);
|
Chris@0
|
179
|
Chris@0
|
180 /**
|
Chris@0
|
181 * Marks cache items as invalid.
|
Chris@0
|
182 *
|
Chris@0
|
183 * Invalid items may be returned in later calls to get(), if the $allow_invalid
|
Chris@0
|
184 * argument is TRUE.
|
Chris@0
|
185 *
|
Chris@0
|
186 * @param string[] $cids
|
Chris@0
|
187 * An array of cache IDs to invalidate.
|
Chris@0
|
188 *
|
Chris@0
|
189 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
|
Chris@0
|
190 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
|
Chris@0
|
191 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
|
Chris@0
|
192 */
|
Chris@0
|
193 public function invalidateMultiple(array $cids);
|
Chris@0
|
194
|
Chris@0
|
195 /**
|
Chris@0
|
196 * Marks all cache items as invalid.
|
Chris@0
|
197 *
|
Chris@0
|
198 * Invalid items may be returned in later calls to get(), if the $allow_invalid
|
Chris@0
|
199 * argument is TRUE.
|
Chris@0
|
200 *
|
Chris@0
|
201 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
|
Chris@0
|
202 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
|
Chris@0
|
203 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
|
Chris@0
|
204 */
|
Chris@0
|
205 public function invalidateAll();
|
Chris@0
|
206
|
Chris@0
|
207 /**
|
Chris@0
|
208 * Performs garbage collection on a cache bin.
|
Chris@0
|
209 *
|
Chris@0
|
210 * The backend may choose to delete expired or invalidated items.
|
Chris@0
|
211 */
|
Chris@0
|
212 public function garbageCollection();
|
Chris@0
|
213
|
Chris@0
|
214 /**
|
Chris@0
|
215 * Remove a cache bin.
|
Chris@0
|
216 */
|
Chris@0
|
217 public function removeBin();
|
Chris@0
|
218
|
Chris@0
|
219 }
|