1: | <?php declare(strict_types=1); |
2: | |
3: | namespace Salient\Contract\Cache; |
4: | |
5: | use Psr\SimpleCache\CacheInterface as PsrCacheInterface; |
6: | use DateInterval; |
7: | use DateTimeInterface; |
8: | use LogicException; |
9: | |
10: | /** |
11: | * @api |
12: | */ |
13: | interface CacheInterface extends PsrCacheInterface |
14: | { |
15: | /** |
16: | * Store an item under a given key |
17: | * |
18: | * @param string $key |
19: | * @param mixed $value |
20: | * @param DateTimeInterface|DateInterval|int|null $ttl The value's TTL in |
21: | * seconds or as a {@see DateInterval}, a {@see DateTimeInterface} |
22: | * representing its expiration time, or `null` if it should be cached |
23: | * indefinitely. |
24: | * |
25: | * Providing an integer less than or equal to `0` has the same effect as |
26: | * calling `delete($key)`. |
27: | * @return true |
28: | */ |
29: | public function set($key, $value, $ttl = null): bool; |
30: | |
31: | /** |
32: | * Check if an item exists and has not expired |
33: | * |
34: | * @param string $key |
35: | */ |
36: | public function has($key): bool; |
37: | |
38: | /** |
39: | * Retrieve an item stored under a given key |
40: | * |
41: | * @param string $key |
42: | * @param mixed $default |
43: | * @return mixed `$default` if the item has expired or doesn't exist. |
44: | */ |
45: | public function get($key, $default = null); |
46: | |
47: | /** |
48: | * Retrieve an instance of a class stored under a given key |
49: | * |
50: | * @template T of object |
51: | * |
52: | * @param string $key |
53: | * @param class-string<T> $class |
54: | * @param T|null $default |
55: | * @return T|null `$default` if the item has expired, doesn't exist or is |
56: | * not an instance of `$class`. |
57: | */ |
58: | public function getInstanceOf($key, string $class, ?object $default = null): ?object; |
59: | |
60: | /** |
61: | * Retrieve an array stored under a given key |
62: | * |
63: | * @param string $key |
64: | * @param mixed[]|null $default |
65: | * @return mixed[]|null `$default` if the item has expired, doesn't exist or |
66: | * is not an array. |
67: | */ |
68: | public function getArray($key, ?array $default = null): ?array; |
69: | |
70: | /** |
71: | * Retrieve an integer stored under a given key |
72: | * |
73: | * @param string $key |
74: | * @return int|null `$default` if the item has expired, doesn't exist or is |
75: | * not an integer. |
76: | */ |
77: | public function getInt($key, ?int $default = null): ?int; |
78: | |
79: | /** |
80: | * Retrieve a string stored under a given key |
81: | * |
82: | * @param string $key |
83: | * @return string|null `$default` if the item has expired, doesn't exist or |
84: | * is not a string. |
85: | */ |
86: | public function getString($key, ?string $default = null): ?string; |
87: | |
88: | /** |
89: | * Delete an item stored under a given key |
90: | * |
91: | * @param string $key |
92: | * @return true |
93: | */ |
94: | public function delete($key): bool; |
95: | |
96: | /** |
97: | * Delete all items |
98: | * |
99: | * @return true |
100: | */ |
101: | public function clear(): bool; |
102: | |
103: | /** |
104: | * Store items under the given keys |
105: | * |
106: | * @param iterable<string,mixed> $values |
107: | * @param DateTimeInterface|DateInterval|int|null $ttl |
108: | * @return true |
109: | */ |
110: | public function setMultiple($values, $ttl = null): bool; |
111: | |
112: | /** |
113: | * Retrieve items stored under the given keys |
114: | * |
115: | * @param iterable<string> $keys |
116: | * @param mixed $default |
117: | * @return iterable<string,mixed> |
118: | */ |
119: | public function getMultiple($keys, $default = null); |
120: | |
121: | /** |
122: | * Delete items stored under the given keys |
123: | * |
124: | * @param iterable<string> $keys |
125: | * @return true |
126: | */ |
127: | public function deleteMultiple($keys): bool; |
128: | |
129: | /** |
130: | * Get the number of unexpired items in the store |
131: | */ |
132: | public function getItemCount(): int; |
133: | |
134: | /** |
135: | * Get a list of keys under which unexpired items are stored |
136: | * |
137: | * @return string[] |
138: | */ |
139: | public function getItemKeys(): array; |
140: | |
141: | /** |
142: | * Get a copy of the store where items do not expire over time |
143: | * |
144: | * Returns an instance where items expire relative to the time of the call |
145: | * to {@see asOfNow()}, allowing clients to mitigate race conditions like |
146: | * items expiring or being replaced between subsequent calls. |
147: | * |
148: | * Only one copy of the store can be open at a time. Copies are closed via |
149: | * {@see close()} or by going out of scope. |
150: | * |
151: | * @param int|null $now If given, items expire relative to this Unix |
152: | * timestamp instead of the time {@see asOfNow()} is called. |
153: | * @return static |
154: | * @throws LogicException if the store is a copy, or if another copy of the |
155: | * store is open. |
156: | */ |
157: | public function asOfNow(?int $now = null): CacheInterface; |
158: | |
159: | /** |
160: | * Close the store and any underlying resources |
161: | * |
162: | * If the store is an instance returned by {@see asOfNow()}, the original |
163: | * instance remains open after any locks held by the copy are released. |
164: | */ |
165: | public function close(): void; |
166: | } |
167: |