annotate core/lib/Drupal/Core/Cache/CacheBackendInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
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 }