1	<?php
2	declare(strict_types=1);
3	/**
4	* Pop PHP Framework (https://www.popphp.org/)
5	*
6	* @link       https://github.com/popphp/popphp-framework
7	* @author     Nick Sagona, III <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Audit\Adapter;
16
17	/**
18	* Auditor adapter interface
19	*
20	* @category   Pop
21	* @package    Pop\Audit
22	* @author     Nick Sagona, III <nick@popphp.org>
23	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
24	* @license    https://www.popphp.org/license     New BSD License
25	* @version    3.0.0
26	*/
27	interface AdapterInterface
28	{
29
30	/**
31	* Set the model name
32	*
33	* @param  string $model
34	* @return AdapterInterface
35	*/
36	public function setModel(string $model): AdapterInterface;
37
38	/**
39	* Set the model ID
40	*
41	* @param  int|string $modelId
42	* @return AdapterInterface
43	*/
44	public function setModelId(int|string $modelId): AdapterInterface;
45
46	/**
47	* Get the model name
48	*
49	* @return string|null
50	*/
51	public function getModel(): string|null;
52
53	/**
54	* Get the model ID
55	*
56	* @return int|string|null
57	*/
58	public function getModelId(): int|string|null;
59
60	/**
61	* Get the action
62	*
63	* @return string|null
64	*/
65	public function getAction(): string|null;
66
67	/**
68	* Get the original model state differences
69	*
70	* @return array
71	*/
72	public function getOriginal(): array;
73
74	/**
75	* Get the modified model state differences
76	*
77	* @return array
78	*/
79	public function getModified(): array;
80
81	/**
82	* Set the username
83	*
84	* @param  string $username
85	* @return AdapterInterface
86	*/
87	public function setUsername(string $username): AdapterInterface;
88
89	/**
90	* Set the user ID
91	*
92	* @param  int|string $userId
93	* @return AdapterInterface
94	*/
95	public function setUserId(int|string $userId): AdapterInterface;
96
97	/**
98	* Set the domain
99	*
100	* @param  string $domain
101	* @return AdapterInterface
102	*/
103	public function setDomain(string $domain): AdapterInterface;
104
105	/**
106	* Set the route
107	*
108	* @param  string $route
109	* @return AdapterInterface
110	*/
111	public function setRoute(string $route): AdapterInterface;
112
113	/**
114	* Set the method
115	*
116	* @param  string $method
117	* @return AdapterInterface
118	*/
119	public function setMethod(string $method): AdapterInterface;
120
121	/**
122	* Set the metadata
123	*
124	* @param  array $metadata
125	* @return AdapterInterface
126	*/
127	public function setMetadata(array $metadata): AdapterInterface;
128
129	/**
130	* Add to the metadata
131	*
132	* @param  string $name
133	* @param  mixed $value
134	* @return AdapterInterface
135	*/
136	public function addMetadata(string $name, mixed $value): AdapterInterface;
137
138	/**
139	* Get the username
140	*
141	* @return string|null
142	*/
143	public function getUsername(): string|null;
144
145	/**
146	* Get the user ID
147	*
148	* @return int|string|null
149	*/
150	public function getUserId(): int|string|null;
151
152	/**
153	* Get the domain
154	*
155	* @return string|null
156	*/
157	public function getDomain(): string|null;
158
159	/**
160	* Get the route
161	*
162	* @return string|null
163	*/
164	public function getRoute(): string|null;
165
166	/**
167	* Get the method
168	*
169	* @return string|null
170	*/
171	public function getMethod(): string|null;
172
173	/**
174	* Determine if there is metadata
175	*
176	* @param  ?string $name
177	* @return bool
178	*/
179	public function hasMetadata(?string $name = null): bool;
180
181	/**
182	* Get the metadata
183	*
184	* @param  ?string $name
185	* @return mixed
186	*/
187	public function getMetadata(?string $name = null): mixed;
188
189	/**
190	* Set the final state data
191	*
192	* @param  array $state
193	* @return AdapterInterface
194	*/
195	public function setStateData(array $state): AdapterInterface;
196
197	/**
198	* Get the final state
199	*
200	* @param  ?string $name
201	* @return mixed
202	*/
203	public function getStateData(?string $name = null): mixed;
204
205	/**
206	* Determine if there is a final state
207	*
208	* @param  ?string $name
209	* @return bool
210	*/
211	public function hasStateData(?string $name = null): bool;
212
213	/**
214	* Set the differences in values between the model states (that have already been processed)
215	*
216	* @param  array $old
217	* @param  array $new
218	* @return AdapterInterface
219	*/
220	public function setDiff(array $old, array $new): AdapterInterface;
221
222	/**
223	* Resolve the differences in values between the model states
224	*
225	* @param  array $old
226	* @param  array $new
227	* @param  bool  $state
228	* @return AdapterInterface
229	*/
230	public function resolveDiff(array $old, array $new, bool $state = true): AdapterInterface;
231
232	/**
233	* Check if the model states are different
234	*
235	* @return bool
236	*/
237	public function hasDiff(): bool;
238
239	/**
240	* Prepare data
241	*
242	* @param  bool $jsonEncode
243	* @return array
244	*/
245	public function prepareData(bool $jsonEncode = true): array;
246
247	/**
248	* Send the results of the audit
249	*
250	* @return mixed
251	*/
252	public function send(): mixed;
253
254	/**
255	* Get model states
256	*
257	* @return array
258	*/
259	public function getStates(): array;
260
261	/**
262	* Get model state by ID
263	*
264	* @param  int|string $id
265	* @return array
266	*/
267	public function getStateById(int|string $id): array;
268
269	/**
270	* Get model state by model
271	*
272	* @param  string          $model
273	* @param  int|string|null $modelId
274	* @return array
275	*/
276	public function getStateByModel(string $model, int|string|null $modelId = null): array;
277
278	/**
279	* Get model state by timestamp
280	*
281	* @param  int  $from
282	* @param  ?int $backTo
283	* @return array
284	*/
285	public function getStateByTimestamp(int $from, ?int $backTo = null): array;
286
287	/**
288	* Get model state by date
289	*
290	* @param  string $from
291	* @param  string $backTo
292	* @return array
293	*/
294	public function getStateByDate(string $from, ?string $backTo = null): array;
295
296	/**
297	* Get model snapshot by ID
298	*
299	* @param  int|string $id
300	* @param  bool       $post
301	* @return array
302	*/
303	public function getSnapshot(int|string $id, bool $post = false): array;
304
305	}