3 namespace Drupal\Core\Cache;
6 * Defines an interface for cache implementations.
8 * All cache implementations have to implement this interface.
9 * Drupal\Core\Cache\DatabaseBackend provides the default implementation, which
10 * can be consulted as an example.
12 * The cache indentifiers are case sensitive.
16 interface CacheBackendInterface {
19 * Indicates that the item should never be removed unless explicitly deleted.
21 const CACHE_PERMANENT = -1;
24 * Returns data from the persistent cache.
27 * The cache ID of the data to retrieve.
28 * @param bool $allow_invalid
29 * (optional) If TRUE, a cache item may be returned even if it is expired or
30 * has been invalidated. Such items may sometimes be preferred, if the
31 * alternative is recalculating the value stored in the cache, especially
32 * if another concurrent request is already recalculating the same value.
33 * The "valid" property of the returned object indicates whether the item is
34 * valid or not. Defaults to FALSE.
36 * @return object|false
37 * The cache item or FALSE on failure.
39 * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
41 public function get($cid, $allow_invalid = FALSE);
44 * Returns data from the persistent cache when given an array of cache IDs.
47 * An array of cache IDs for the data to retrieve. This is passed by
48 * reference, and will have the IDs successfully returned from cache
50 * @param bool $allow_invalid
51 * (optional) If TRUE, cache items may be returned even if they have expired
52 * or been invalidated. Such items may sometimes be preferred, if the
53 * alternative is recalculating the value stored in the cache, especially
54 * if another concurrent thread is already recalculating the same value. The
55 * "valid" property of the returned objects indicates whether the items are
56 * valid or not. Defaults to FALSE.
59 * An array of cache item objects indexed by cache ID.
61 * @see \Drupal\Core\Cache\CacheBackendInterface::get()
63 public function getMultiple(&$cids, $allow_invalid = FALSE);
66 * Stores data in the persistent cache.
68 * Core cache implementations set the created time on cache item with
69 * microtime(TRUE) rather than REQUEST_TIME_FLOAT, because the created time
70 * of cache items should match when they are created, not when the request
71 * started. Apart from being more accurate, this increases the chance an
72 * item will legitimately be considered valid.
75 * The cache ID of the data to store.
77 * The data to store in the cache.
78 * Some storage engines only allow objects up to a maximum of 1MB in size to
79 * be stored by default. When caching large arrays or similar, take care to
80 * ensure $data does not exceed this size.
82 * One of the following values:
83 * - CacheBackendInterface::CACHE_PERMANENT: Indicates that the item should
84 * not be removed unless it is deleted explicitly.
85 * - A Unix timestamp: Indicates that the item will be considered invalid
86 * after this time, i.e. it will not be returned by get() unless
87 * $allow_invalid has been set to TRUE. When the item has expired, it may
88 * be permanently deleted by the garbage collector at any time.
90 * An array of tags to be stored with the cache item. These should normally
91 * identify objects used to build the cache item, which should trigger
92 * cache invalidation when updated. For example if a cached item represents
93 * a node, both the node ID and the author's user ID might be passed in as
94 * tags. For example array('node' => array(123), 'user' => array(92)).
96 * @see \Drupal\Core\Cache\CacheBackendInterface::get()
97 * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
99 public function set($cid, $data, $expire = Cache::PERMANENT, array $tags = []);
102 * Store multiple items in the persistent cache.
104 * @param array $items
105 * An array of cache items, keyed by cid. In the form:
109 * // Required, will be automatically serialized if not a string.
111 * // Optional, defaults to CacheBackendInterface::CACHE_PERMANENT.
112 * 'expire' => CacheBackendInterface::CACHE_PERMANENT,
113 * // (optional) The cache tags for this item, see CacheBackendInterface::set().
119 public function setMultiple(array $items);
122 * Deletes an item from the cache.
124 * If the cache item is being deleted because it is no longer "fresh", you may
125 * consider using invalidate() instead. This allows callers to retrieve the
126 * invalid item by calling get() with $allow_invalid set to TRUE. In some cases
127 * an invalid item may be acceptable rather than having to rebuild the cache.
130 * The cache ID to delete.
132 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
133 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
134 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
136 public function delete($cid);
139 * Deletes multiple items from the cache.
141 * If the cache items are being deleted because they are no longer "fresh",
142 * you may consider using invalidateMultiple() instead. This allows callers to
143 * retrieve the invalid items by calling get() with $allow_invalid set to TRUE.
144 * In some cases an invalid item may be acceptable rather than having to
148 * An array of cache IDs to delete.
150 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
151 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
152 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
154 public function deleteMultiple(array $cids);
157 * Deletes all cache items in a bin.
159 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
160 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
161 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
163 public function deleteAll();
166 * Marks a cache item as invalid.
168 * Invalid items may be returned in later calls to get(), if the $allow_invalid
172 * The cache ID to invalidate.
174 * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
175 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
176 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
178 public function invalidate($cid);
181 * Marks cache items as invalid.
183 * Invalid items may be returned in later calls to get(), if the $allow_invalid
186 * @param string[] $cids
187 * An array of cache IDs to invalidate.
189 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
190 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
191 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
193 public function invalidateMultiple(array $cids);
196 * Marks all cache items as invalid.
198 * Invalid items may be returned in later calls to get(), if the $allow_invalid
201 * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
202 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
203 * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
205 public function invalidateAll();
208 * Performs garbage collection on a cache bin.
210 * The backend may choose to delete expired or invalidated items.
212 public function garbageCollection();
215 * Remove a cache bin.
217 public function removeBin();