1	<?php
2	/**
3	* Jingga
4	*
5	* PHP Version 8.1
6	*
7	* @package   phpOMS\DataStorage\Cache\Connection
8	* @copyright Dennis Eichhorn
9	* @license   OMS License 2.0
10	* @version   1.0.0
11	* @link      https://jingga.app
12	*/
13	declare(strict_types=1);
14
15	namespace phpOMS\DataStorage\Cache\Connection;
16
17	use phpOMS\DataStorage\DataStorageConnectionInterface;
18
19	/**
20	* Cache interface.
21	*
22	* @package phpOMS\DataStorage\Cache\Connection
23	* @license OMS License 2.0
24	* @link    https://jingga.app
25	* @since   1.0.0
26	*/
27	interface ConnectionInterface extends DataStorageConnectionInterface
28	{
29	/**
30	* Updating or adding cache data.
31	*
32	* @param int|string $key    Unique cache key
33	* @param mixed      $value  Cache value
34	* @param int        $expire Valid duration (in s). Negative expiration means no expiration.
35	*
36	* @return void
37	*
38	* @since 1.0.0
39	*/
40	public function set(int | string $key, mixed $value, int $expire = -1) : void;
41
42	/**
43	* Increment value.
44	*
45	* @param int|string $key   Unique cache key
46	* @param int        $value By value
47	*
48	* @return bool
49	*
50	* @since 1.0.0
51	*/
52	public function increment(int | string $key, int $value = 1) : bool;
53
54	/**
55	* Decrement value.
56	*
57	* @param int|string $key   Unique cache key
58	* @param int        $value By value
59	*
60	* @return bool
61	*
62	* @since 1.0.0
63	*/
64	public function decrement(int | string $key, int $value = 1) : bool;
65
66	/**
67	* Rename cache key.
68	*
69	* @param int|string $old    Unique cache key
70	* @param int|string $new    Unique cache key
71	* @param int        $expire Valid duration (in s). Negative expiration means no expiration.
72	*
73	* @return bool
74	*
75	* @since 1.0.0
76	*/
77	public function rename(int | string $old, int | string $new, int $expire = -1) : bool;
78
79	/**
80	* Adding new data if it doesn't exist.
81	*
82	* @param int|string $key    Unique cache key
83	* @param mixed      $value  Cache value
84	* @param int        $expire Valid duration (in s)
85	*
86	* @return bool
87	*
88	* @since 1.0.0
89	*/
90	public function add(int | string $key, mixed $value, int $expire = -1) : bool;
91
92	/**
93	* Get cache by key.
94	*
95	* @param int|string $key    Unique cache key
96	* @param int        $expire Valid duration (in s). In case the data needs to be newer than the defined expiration time. If the expiration date is larger than the defined expiration time and supposed to be expired it will not remove the outdated cache.
97	*
98	* @return mixed Cache value
99	*
100	* @since 1.0.0
101	*/
102	public function get(int | string $key, int $expire = -1) : mixed;
103
104	/**
105	* Exists cache by key.
106	*
107	* @param int|string $key    Unique cache key
108	* @param int        $expire Valid duration (in s). In case the data needs to be newer than the defined expiration time. If the expiration date is larger than the defined expiration time and supposed to be expired it will not remove the outdated cache.
109	*
110	* @return bool
111	*
112	* @since 1.0.0
113	*/
114	public function exists(int | string $key, int $expire = -1) : bool;
115
116	/**
117	* Remove value by key.
118	*
119	* @param int|string $key    Unique cache key
120	* @param int        $expire Valid duration (in s)
121	*
122	* @return bool
123	*
124	* @since 1.0.0
125	*/
126	public function delete(int | string $key, int $expire = -1) : bool;
127
128	/**
129	* Removing all cache elements larger or equal to the expiration date. Call flushAll for removing persistent cache elements (expiration is negative) as well.
130	*
131	* @param int $expire Valid duration (in s)
132	*
133	* @return bool
134	*
135	* @since 1.0.0
136	*/
137	public function flush(int $expire = 0) : bool;
138
139	/**
140	* Removing all elements from cache (invalidate cache).
141	*
142	* @return bool
143	*
144	* @since 1.0.0
145	*/
146	public function flushAll() : bool;
147
148	/**
149	* Updating existing value/key.
150	*
151	* @param int|string $key    Unique cache key
152	* @param mixed      $value  Cache value
153	* @param int        $expire Valid duration (in s)
154	*
155	* @return bool
156	*
157	* @since 1.0.0
158	*/
159	public function replace(int | string $key, mixed $value, int $expire = -1) : bool;
160
161	/**
162	* Updating expire.
163	*
164	* @param int|string $key    Unique cache key
165	* @param int        $expire Valid duration (in s)
166	*
167	* @return bool
168	*
169	* @since 1.0.0
170	*/
171	public function updateExpire(int | string $key, int $expire = -1) : bool;
172
173	/**
174	* Requesting cache stats.
175	*
176	* @return mixed[] Stats array
177	*
178	* @since 1.0.0
179	*/
180	public function stats() : array;
181
182	/**
183	* Get the threshold required to cache data using this cache.
184	*
185	* @return int Storage threshold
186	*
187	* @since 1.0.0
188	*/
189	public function getThreshold() : int;
190	}