Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Cache;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for cache implementations.
Chris@0:  *
Chris@0:  * All cache implementations have to implement this interface.
Chris@0:  * Drupal\Core\Cache\DatabaseBackend provides the default implementation, which
Chris@0:  * can be consulted as an example.
Chris@0:  *
Chris@17:  * The cache identifiers are case sensitive.
Chris@0:  *
Chris@0:  * @ingroup cache
Chris@0:  */
Chris@0: interface CacheBackendInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Indicates that the item should never be removed unless explicitly deleted.
Chris@0:    */
Chris@0:   const CACHE_PERMANENT = -1;
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns data from the persistent cache.
Chris@0:    *
Chris@0:    * @param string $cid
Chris@0:    *   The cache ID of the data to retrieve.
Chris@0:    * @param bool $allow_invalid
Chris@0:    *   (optional) If TRUE, a cache item may be returned even if it is expired or
Chris@0:    *   has been invalidated. Such items may sometimes be preferred, if the
Chris@0:    *   alternative is recalculating the value stored in the cache, especially
Chris@0:    *   if another concurrent request is already recalculating the same value.
Chris@0:    *   The "valid" property of the returned object indicates whether the item is
Chris@0:    *   valid or not. Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return object|false
Chris@0:    *   The cache item or FALSE on failure.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
Chris@0:    */
Chris@0:   public function get($cid, $allow_invalid = FALSE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns data from the persistent cache when given an array of cache IDs.
Chris@0:    *
Chris@0:    * @param array $cids
Chris@0:    *   An array of cache IDs for the data to retrieve. This is passed by
Chris@0:    *   reference, and will have the IDs successfully returned from cache
Chris@0:    *   removed.
Chris@0:    * @param bool $allow_invalid
Chris@0:    *   (optional) If TRUE, cache items may be returned even if they have expired
Chris@0:    *   or been invalidated. Such items may sometimes be preferred, if the
Chris@0:    *   alternative is recalculating the value stored in the cache, especially
Chris@0:    *   if another concurrent thread is already recalculating the same value. The
Chris@0:    *   "valid" property of the returned objects indicates whether the items are
Chris@0:    *   valid or not. Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of cache item objects indexed by cache ID.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::get()
Chris@0:    */
Chris@0:   public function getMultiple(&$cids, $allow_invalid = FALSE);
Chris@0: 
Chris@0:   /**
Chris@0:    * Stores data in the persistent cache.
Chris@0:    *
Chris@0:    * Core cache implementations set the created time on cache item with
Chris@0:    * microtime(TRUE) rather than REQUEST_TIME_FLOAT, because the created time
Chris@0:    * of cache items should match when they are created, not when the request
Chris@0:    * started. Apart from being more accurate, this increases the chance an
Chris@0:    * item will legitimately be considered valid.
Chris@0:    *
Chris@0:    * @param string $cid
Chris@0:    *   The cache ID of the data to store.
Chris@0:    * @param mixed $data
Chris@0:    *   The data to store in the cache.
Chris@0:    *   Some storage engines only allow objects up to a maximum of 1MB in size to
Chris@0:    *   be stored by default. When caching large arrays or similar, take care to
Chris@0:    *   ensure $data does not exceed this size.
Chris@0:    * @param int $expire
Chris@0:    *   One of the following values:
Chris@0:    *   - CacheBackendInterface::CACHE_PERMANENT: Indicates that the item should
Chris@0:    *     not be removed unless it is deleted explicitly.
Chris@0:    *   - A Unix timestamp: Indicates that the item will be considered invalid
Chris@0:    *     after this time, i.e. it will not be returned by get() unless
Chris@0:    *     $allow_invalid has been set to TRUE. When the item has expired, it may
Chris@0:    *     be permanently deleted by the garbage collector at any time.
Chris@0:    * @param array $tags
Chris@0:    *   An array of tags to be stored with the cache item. These should normally
Chris@0:    *   identify objects used to build the cache item, which should trigger
Chris@0:    *   cache invalidation when updated. For example if a cached item represents
Chris@0:    *   a node, both the node ID and the author's user ID might be passed in as
Chris@0:    *   tags. For example ['node:123', 'node:456', 'user:789'].
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::get()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::getMultiple()
Chris@0:    */
Chris@0:   public function set($cid, $data, $expire = Cache::PERMANENT, array $tags = []);
Chris@0: 
Chris@0:   /**
Chris@0:    * Store multiple items in the persistent cache.
Chris@0:    *
Chris@0:    * @param array $items
Chris@0:    *   An array of cache items, keyed by cid. In the form:
Chris@0:    *   @code
Chris@0:    *   $items = array(
Chris@0:    *     $cid => array(
Chris@0:    *       // Required, will be automatically serialized if not a string.
Chris@0:    *       'data' => $data,
Chris@0:    *       // Optional, defaults to CacheBackendInterface::CACHE_PERMANENT.
Chris@0:    *       'expire' => CacheBackendInterface::CACHE_PERMANENT,
Chris@0:    *       // (optional) The cache tags for this item, see CacheBackendInterface::set().
Chris@0:    *       'tags' => array(),
Chris@0:    *     ),
Chris@0:    *   );
Chris@0:    *   @endcode
Chris@0:    */
Chris@0:   public function setMultiple(array $items);
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes an item from the cache.
Chris@0:    *
Chris@0:    * If the cache item is being deleted because it is no longer "fresh", you may
Chris@0:    * consider using invalidate() instead. This allows callers to retrieve the
Chris@0:    * invalid item by calling get() with $allow_invalid set to TRUE. In some cases
Chris@0:    * an invalid item may be acceptable rather than having to rebuild the cache.
Chris@0:    *
Chris@0:    * @param string $cid
Chris@0:    *   The cache ID to delete.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
Chris@0:    */
Chris@0:   public function delete($cid);
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes multiple items from the cache.
Chris@0:    *
Chris@0:    * If the cache items are being deleted because they are no longer "fresh",
Chris@0:    * you may consider using invalidateMultiple() instead. This allows callers to
Chris@0:    * retrieve the invalid items by calling get() with $allow_invalid set to TRUE.
Chris@0:    * In some cases an invalid item may be acceptable rather than having to
Chris@0:    * rebuild the cache.
Chris@0:    *
Chris@0:    * @param array $cids
Chris@0:    *   An array of cache IDs to delete.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
Chris@0:    */
Chris@0:   public function deleteMultiple(array $cids);
Chris@0: 
Chris@0:   /**
Chris@0:    * Deletes all cache items in a bin.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
Chris@0:    */
Chris@0:   public function deleteAll();
Chris@0: 
Chris@0:   /**
Chris@0:    * Marks a cache item as invalid.
Chris@0:    *
Chris@0:    * Invalid items may be returned in later calls to get(), if the $allow_invalid
Chris@0:    * argument is TRUE.
Chris@0:    *
Chris@0:    * @param string $cid
Chris@0:    *   The cache ID to invalidate.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::delete()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
Chris@0:    */
Chris@0:   public function invalidate($cid);
Chris@0: 
Chris@0:   /**
Chris@0:    * Marks cache items as invalid.
Chris@0:    *
Chris@0:    * Invalid items may be returned in later calls to get(), if the $allow_invalid
Chris@0:    * argument is TRUE.
Chris@0:    *
Chris@0:    * @param string[] $cids
Chris@0:    *   An array of cache IDs to invalidate.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteMultiple()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateAll()
Chris@0:    */
Chris@0:   public function invalidateMultiple(array $cids);
Chris@0: 
Chris@0:   /**
Chris@0:    * Marks all cache items as invalid.
Chris@0:    *
Chris@0:    * Invalid items may be returned in later calls to get(), if the $allow_invalid
Chris@0:    * argument is TRUE.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::deleteAll()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidate()
Chris@0:    * @see \Drupal\Core\Cache\CacheBackendInterface::invalidateMultiple()
Chris@0:    */
Chris@0:   public function invalidateAll();
Chris@0: 
Chris@0:   /**
Chris@0:    * Performs garbage collection on a cache bin.
Chris@0:    *
Chris@0:    * The backend may choose to delete expired or invalidated items.
Chris@0:    */
Chris@0:   public function garbageCollection();
Chris@0: 
Chris@0:   /**
Chris@0:    * Remove a cache bin.
Chris@0:    */
Chris@0:   public function removeBin();
Chris@0: 
Chris@0: }