[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   1  <?php
   2  
   3  namespace Psr\SimpleCache;
   4  
   5  interface CacheInterface
   6  {
   7      /**
   8       * Fetches a value from the cache.
   9       *
  10       * @param string $key     The unique key of this item in the cache.
  11       * @param mixed  $default Default value to return if the key does not exist.
  12       *
  13       * @return mixed The value of the item from the cache, or $default in case of cache miss.
  14       *
  15       * @throws \Psr\SimpleCache\InvalidArgumentException
  16       *   MUST be thrown if the $key string is not a legal value.
  17       */
  18      public function get(string $key, mixed $default = null): mixed;
  19  
  20      /**
  21       * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
  22       *
  23       * @param string                 $key   The key of the item to store.
  24       * @param mixed                  $value The value of the item to store, must be serializable.
  25       * @param null|int|\DateInterval $ttl   Optional. The TTL value of this item. If no value is sent and
  26       *                                      the driver supports TTL then the library may set a default value
  27       *                                      for it or let the driver take care of that.
  28       *
  29       * @return bool True on success and false on failure.
  30       *
  31       * @throws \Psr\SimpleCache\InvalidArgumentException
  32       *   MUST be thrown if the $key string is not a legal value.
  33       */
  34      public function set(string $key, mixed $value, null|int|\DateInterval $ttl = null): bool;
  35  
  36      /**
  37       * Delete an item from the cache by its unique key.
  38       *
  39       * @param string $key The unique cache key of the item to delete.
  40       *
  41       * @return bool True if the item was successfully removed. False if there was an error.
  42       *
  43       * @throws \Psr\SimpleCache\InvalidArgumentException
  44       *   MUST be thrown if the $key string is not a legal value.
  45       */
  46      public function delete(string $key): bool;
  47  
  48      /**
  49       * Wipes clean the entire cache's keys.
  50       *
  51       * @return bool True on success and false on failure.
  52       */
  53      public function clear(): bool;
  54  
  55      /**
  56       * Obtains multiple cache items by their unique keys.
  57       *
  58       * @param iterable<string> $keys    A list of keys that can be obtained in a single operation.
  59       * @param mixed            $default Default value to return for keys that do not exist.
  60       *
  61       * @return iterable<string, mixed> A list of key => value pairs. Cache keys that do not exist or are stale will have $default as value.
  62       *
  63       * @throws \Psr\SimpleCache\InvalidArgumentException
  64       *   MUST be thrown if $keys is neither an array nor a Traversable,
  65       *   or if any of the $keys are not a legal value.
  66       */
  67      public function getMultiple(iterable $keys, mixed $default = null): iterable;
  68  
  69      /**
  70       * Persists a set of key => value pairs in the cache, with an optional TTL.
  71       *
  72       * @param iterable               $values A list of key => value pairs for a multiple-set operation.
  73       * @param null|int|\DateInterval $ttl    Optional. The TTL value of this item. If no value is sent and
  74       *                                       the driver supports TTL then the library may set a default value
  75       *                                       for it or let the driver take care of that.
  76       *
  77       * @return bool True on success and false on failure.
  78       *
  79       * @throws \Psr\SimpleCache\InvalidArgumentException
  80       *   MUST be thrown if $values is neither an array nor a Traversable,
  81       *   or if any of the $values are not a legal value.
  82       */
  83      public function setMultiple(iterable $values, null|int|\DateInterval $ttl = null): bool;
  84  
  85      /**
  86       * Deletes multiple cache items in a single operation.
  87       *
  88       * @param iterable<string> $keys A list of string-based keys to be deleted.
  89       *
  90       * @return bool True if the items were successfully removed. False if there was an error.
  91       *
  92       * @throws \Psr\SimpleCache\InvalidArgumentException
  93       *   MUST be thrown if $keys is neither an array nor a Traversable,
  94       *   or if any of the $keys are not a legal value.
  95       */
  96      public function deleteMultiple(iterable $keys): bool;
  97  
  98      /**
  99       * Determines whether an item is present in the cache.
 100       *
 101       * NOTE: It is recommended that has() is only to be used for cache warming type purposes
 102       * and not to be used within your live applications operations for get/set, as this method
 103       * is subject to a race condition where your has() will return true and immediately after,
 104       * another script can remove it making the state of your app out of date.
 105       *
 106       * @param string $key The cache item key.
 107       *
 108       * @return bool
 109       *
 110       * @throws \Psr\SimpleCache\InvalidArgumentException
 111       *   MUST be thrown if the $key string is not a legal value.
 112       */
 113      public function has(string $key): bool;
 114  }