| 1 |
<?php |
| 2 |
|
| 3 |
namespace React\Cache; |
| 4 |
|
| 5 |
use React\Promise\PromiseInterface; |
| 6 |
|
| 7 |
interface CacheInterface |
| 8 |
{ |
| 9 |
/** |
| 10 |
* Retrieves an item from the cache. |
| 11 |
* |
| 12 |
* This method will resolve with the cached value on success or with the |
| 13 |
* given `$default` value when no item can be found or when an error occurs. |
| 14 |
* Similarly, an expired cache item (once the time-to-live is expired) is |
| 15 |
* considered a cache miss. |
| 16 |
* |
| 17 |
* ```php |
| 18 |
* $cache |
| 19 |
* ->get('foo') |
| 20 |
* ->then('var_dump'); |
| 21 |
* ``` |
| 22 |
* |
| 23 |
* This example fetches the value of the key `foo` and passes it to the |
| 24 |
* `var_dump` function. You can use any of the composition provided by |
| 25 |
* [promises](https://github.com/reactphp/promise). |
| 26 |
* |
| 27 |
* @param string $key |
| 28 |
* @param mixed $default Default value to return for cache miss or null if not given. |
| 29 |
* @return PromiseInterface<mixed> |
| 30 |
*/ |
| 31 |
public function get($key, $default = null); |
| 32 |
|
| 33 |
/** |
| 34 |
* Stores an item in the cache. |
| 35 |
* |
| 36 |
* This method will resolve with `true` on success or `false` when an error |
| 37 |
* occurs. If the cache implementation has to go over the network to store |
| 38 |
* it, it may take a while. |
| 39 |
* |
| 40 |
* The optional `$ttl` parameter sets the maximum time-to-live in seconds |
| 41 |
* for this cache item. If this parameter is omitted (or `null`), the item |
| 42 |
* will stay in the cache for as long as the underlying implementation |
| 43 |
* supports. Trying to access an expired cache item results in a cache miss, |
| 44 |
* see also [`get()`](#get). |
| 45 |
* |
| 46 |
* ```php |
| 47 |
* $cache->set('foo', 'bar', 60); |
| 48 |
* ``` |
| 49 |
* |
| 50 |
* This example eventually sets the value of the key `foo` to `bar`. If it |
| 51 |
* already exists, it is overridden. |
| 52 |
* |
| 53 |
* This interface does not enforce any particular TTL resolution, so special |
| 54 |
* care may have to be taken if you rely on very high precision with |
| 55 |
* millisecond accuracy or below. Cache implementations SHOULD work on a |
| 56 |
* best effort basis and SHOULD provide at least second accuracy unless |
| 57 |
* otherwise noted. Many existing cache implementations are known to provide |
| 58 |
* microsecond or millisecond accuracy, but it's generally not recommended |
| 59 |
* to rely on this high precision. |
| 60 |
* |
| 61 |
* This interface suggests that cache implementations SHOULD use a monotonic |
| 62 |
* time source if available. Given that a monotonic time source is only |
| 63 |
* available as of PHP 7.3 by default, cache implementations MAY fall back |
| 64 |
* to using wall-clock time. |
| 65 |
* While this does not affect many common use cases, this is an important |
| 66 |
* distinction for programs that rely on a high time precision or on systems |
| 67 |
* that are subject to discontinuous time adjustments (time jumps). |
| 68 |
* This means that if you store a cache item with a TTL of 30s and then |
| 69 |
* adjust your system time forward by 20s, the cache item SHOULD still |
| 70 |
* expire in 30s. |
| 71 |
* |
| 72 |
* @param string $key |
| 73 |
* @param mixed $value |
| 74 |
* @param ?float $ttl |
| 75 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 76 |
*/ |
| 77 |
public function set($key, $value, $ttl = null); |
| 78 |
|
| 79 |
/** |
| 80 |
* Deletes an item from the cache. |
| 81 |
* |
| 82 |
* This method will resolve with `true` on success or `false` when an error |
| 83 |
* occurs. When no item for `$key` is found in the cache, it also resolves |
| 84 |
* to `true`. If the cache implementation has to go over the network to |
| 85 |
* delete it, it may take a while. |
| 86 |
* |
| 87 |
* ```php |
| 88 |
* $cache->delete('foo'); |
| 89 |
* ``` |
| 90 |
* |
| 91 |
* This example eventually deletes the key `foo` from the cache. As with |
| 92 |
* `set()`, this may not happen instantly and a promise is returned to |
| 93 |
* provide guarantees whether or not the item has been removed from cache. |
| 94 |
* |
| 95 |
* @param string $key |
| 96 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 97 |
*/ |
| 98 |
public function delete($key); |
| 99 |
|
| 100 |
/** |
| 101 |
* Retrieves multiple cache items by their unique keys. |
| 102 |
* |
| 103 |
* This method will resolve with an array of cached values on success or with the |
| 104 |
* given `$default` value when an item can not be found or when an error occurs. |
| 105 |
* Similarly, an expired cache item (once the time-to-live is expired) is |
| 106 |
* considered a cache miss. |
| 107 |
* |
| 108 |
* ```php |
| 109 |
* $cache->getMultiple(array('name', 'age'))->then(function (array $values) { |
| 110 |
* $name = $values['name'] ?? 'User'; |
| 111 |
* $age = $values['age'] ?? 'n/a'; |
| 112 |
* |
| 113 |
* echo $name . ' is ' . $age . PHP_EOL; |
| 114 |
* }); |
| 115 |
* ``` |
| 116 |
* |
| 117 |
* This example fetches the cache items for the `name` and `age` keys and |
| 118 |
* prints some example output. You can use any of the composition provided |
| 119 |
* by [promises](https://github.com/reactphp/promise). |
| 120 |
* |
| 121 |
* @param string[] $keys A list of keys that can obtained in a single operation. |
| 122 |
* @param mixed $default Default value to return for keys that do not exist. |
| 123 |
* @return PromiseInterface<array> Returns a promise which resolves to an `array` of cached values |
| 124 |
*/ |
| 125 |
public function getMultiple(array $keys, $default = null); |
| 126 |
|
| 127 |
/** |
| 128 |
* Persists a set of key => value pairs in the cache, with an optional TTL. |
| 129 |
* |
| 130 |
* This method will resolve with `true` on success or `false` when an error |
| 131 |
* occurs. If the cache implementation has to go over the network to store |
| 132 |
* it, it may take a while. |
| 133 |
* |
| 134 |
* The optional `$ttl` parameter sets the maximum time-to-live in seconds |
| 135 |
* for these cache items. If this parameter is omitted (or `null`), these items |
| 136 |
* will stay in the cache for as long as the underlying implementation |
| 137 |
* supports. Trying to access an expired cache items results in a cache miss, |
| 138 |
* see also [`get()`](#get). |
| 139 |
* |
| 140 |
* ```php |
| 141 |
* $cache->setMultiple(array('foo' => 1, 'bar' => 2), 60); |
| 142 |
* ``` |
| 143 |
* |
| 144 |
* This example eventually sets the list of values - the key `foo` to 1 value |
| 145 |
* and the key `bar` to 2. If some of the keys already exist, they are overridden. |
| 146 |
* |
| 147 |
* @param array $values A list of key => value pairs for a multiple-set operation. |
| 148 |
* @param ?float $ttl Optional. The TTL value of this item. |
| 149 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 150 |
*/ |
| 151 |
public function setMultiple(array $values, $ttl = null); |
| 152 |
|
| 153 |
/** |
| 154 |
* Deletes multiple cache items in a single operation. |
| 155 |
* |
| 156 |
* @param string[] $keys A list of string-based keys to be deleted. |
| 157 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 158 |
*/ |
| 159 |
public function deleteMultiple(array $keys); |
| 160 |
|
| 161 |
/** |
| 162 |
* Wipes clean the entire cache. |
| 163 |
* |
| 164 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 165 |
*/ |
| 166 |
public function clear(); |
| 167 |
|
| 168 |
/** |
| 169 |
* Determines whether an item is present in the cache. |
| 170 |
* |
| 171 |
* This method will resolve with `true` on success or `false` when no item can be found |
| 172 |
* or when an error occurs. Similarly, an expired cache item (once the time-to-live |
| 173 |
* is expired) is considered a cache miss. |
| 174 |
* |
| 175 |
* ```php |
| 176 |
* $cache |
| 177 |
* ->has('foo') |
| 178 |
* ->then('var_dump'); |
| 179 |
* ``` |
| 180 |
* |
| 181 |
* This example checks if the value of the key `foo` is set in the cache and passes |
| 182 |
* the result to the `var_dump` function. You can use any of the composition provided by |
| 183 |
* [promises](https://github.com/reactphp/promise). |
| 184 |
* |
| 185 |
* NOTE: It is recommended that has() is only to be used for cache warming type purposes |
| 186 |
* and not to be used within your live applications operations for get/set, as this method |
| 187 |
* is subject to a race condition where your has() will return true and immediately after, |
| 188 |
* another script can remove it making the state of your app out of date. |
| 189 |
* |
| 190 |
* @param string $key The cache item key. |
| 191 |
* @return PromiseInterface<bool> Returns a promise which resolves to `true` on success or `false` on error |
| 192 |
*/ |
| 193 |
public function has($key); |
| 194 |
} |