www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Cache/CacheBackendInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Cache;
   4
   5 /**
   6  * Defines an interface for cache implementations.
   7  *
   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.
  11  *
  12  * The cache indentifiers are case sensitive.
  13  *
  14  * @ingroup cache
  15  */
  16 interface CacheBackendInterface {
  17
  18   /**
  19    * Indicates that the item should never be removed unless explicitly deleted.
  20    */
  21   const CACHE_PERMANENT = -1;
  22
  23   /**
  24    * Returns data from the persistent cache.
  25    *
  26    * @param string $cid
  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.
  35    *
  36    * @return object|false
  37    *   The cache item or FALSE on failure.
  38    *
  39    * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
  40    */
  41   public function get($cid, $allow_invalid = FALSE);
  42
  43   /**
  44    * Returns data from the persistent cache when given an array of cache IDs.
  45    *
  46    * @param array $cids
  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
  49    *   removed.
  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.
  57    *
  58    * @return array
  59    *   An array of cache item objects indexed by cache ID.
  60    *
  61    * @see \Drupal\Core\Cache\CacheBackendInterface::get()
  62    */
  63   public function getMultiple(&$cids, $allow_invalid = FALSE);
  64
  65   /**
  66    * Stores data in the persistent cache.
  67    *
  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.
  73    *
  74    * @param string $cid
  75    *   The cache ID of the data to store.
  76    * @param mixed $data
  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.
  81    * @param int $expire
  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.
  89    * @param array $tags
  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)).
  95    *
  96    * @see \Drupal\Core\Cache\CacheBackendInterface::get()
  97    * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
  98    */
  99   public function set($cid, $data, $expire = Cache::PERMANENT, array $tags = []);
 100
 101   /**
 102    * Store multiple items in the persistent cache.
 103    *
 104    * @param array $items
 105    *   An array of cache items, keyed by cid. In the form:
 106    *   @code
 107    *   $items = array(
 108    *     $cid => array(
 109    *       // Required, will be automatically serialized if not a string.
 110    *       'data' => $data,
 111    *       // Optional, defaults to CacheBackendInterface::CACHE_PERMANENT.
 112    *       'expire' => CacheBackendInterface::CACHE_PERMANENT,
 113    *       // (optional) The cache tags for this item, see CacheBackendInterface::set().
 114    *       'tags' => array(),
 115    *     ),
 116    *   );
 117    *   @endcode
 118    */
 119   public function setMultiple(array $items);
 120
 121   /**
 122    * Deletes an item from the cache.
 123    *
 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.
 128    *
 129    * @param string $cid
 130    *   The cache ID to delete.
 131    *
 132    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
 133    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
 134    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
 135    */
 136   public function delete($cid);
 137
 138   /**
 139    * Deletes multiple items from the cache.
 140    *
 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
 145    * rebuild the cache.
 146    *
 147    * @param array $cids
 148    *   An array of cache IDs to delete.
 149    *
 150    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
 151    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
 152    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
 153    */
 154   public function deleteMultiple(array $cids);
 155
 156   /**
 157    * Deletes all cache items in a bin.
 158    *
 159    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
 160    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
 161    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
 162    */
 163   public function deleteAll();
 164
 165   /**
 166    * Marks a cache item as invalid.
 167    *
 168    * Invalid items may be returned in later calls to get(), if the $allow_invalid
 169    * argument is TRUE.
 170    *
 171    * @param string $cid
 172    *   The cache ID to invalidate.
 173    *
 174    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
 175    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
 176    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
 177    */
 178   public function invalidate($cid);
 179
 180   /**
 181    * Marks cache items as invalid.
 182    *
 183    * Invalid items may be returned in later calls to get(), if the $allow_invalid
 184    * argument is TRUE.
 185    *
 186    * @param string[] $cids
 187    *   An array of cache IDs to invalidate.
 188    *
 189    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
 190    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
 191    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
 192    */
 193   public function invalidateMultiple(array $cids);
 194
 195   /**
 196    * Marks all cache items as invalid.
 197    *
 198    * Invalid items may be returned in later calls to get(), if the $allow_invalid
 199    * argument is TRUE.
 200    *
 201    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
 202    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
 203    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
 204    */
 205   public function invalidateAll();
 206
 207   /**
 208    * Performs garbage collection on a cache bin.
 209    *
 210    * The backend may choose to delete expired or invalidated items.
 211    */
 212   public function garbageCollection();
 213
 214   /**
 215    * Remove a cache bin.
 216    */
 217   public function removeBin();
 218
 219 }