friendship ended with social-app. php is my new best friend
veryroundbird.house
1<?php
2
3namespace React\Cache;
4
5use React\Promise\PromiseInterface;
6
7interface 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}