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\Db\Adapter;
16
17	use Pop\Db\Sql;
18
19	/**
20	* Db adapter interface
21	*
22	* @category   Pop
23	* @package    Pop\Db
24	* @author     Nick Sagona, III <nick@popphp.org>
25	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
26	* @license    https://www.popphp.org/license     New BSD License
27	* @version    7.0.0
28	*/
29	interface AdapterInterface
30	{
31
32	/**
33	* Connect to the database
34	*
35	* @param  array $options
36	* @return AdapterInterface
37	*/
38	public function connect(array $options = []): AdapterInterface;
39
40	/**
41	* Set database connection options
42	*
43	* @param  array $options
44	* @return AdapterInterface
45	*/
46	public function setOptions(array $options): AdapterInterface;
47
48	/**
49	* Get database connection options
50	*
51	* @return array
52	*/
53	public function getOptions(): array;
54
55	/**
56	* Has database connection options
57	*
58	* @return bool
59	*/
60	public function hasOptions(): bool;
61
62	/**
63	* Begin a transaction
64	*
65	* @return AdapterInterface
66	*/
67	public function beginTransaction(): AdapterInterface;
68
69	/**
70	* Commit a transaction
71	*
72	* @return AdapterInterface
73	*/
74	public function commit(): AdapterInterface;
75
76	/**
77	* Rollback a transaction
78	*
79	* @return AdapterInterface
80	*/
81	public function rollback(): AdapterInterface;
82
83	/**
84	* Check if adapter is in the middle of an open transaction
85	*
86	* @return bool
87	*/
88	public function isTransaction(): bool;
89
90	/**
91	* Get transaction depth
92	*
93	* @return int
94	*/
95	public function getTransactionDepth(): int;
96
97	/**
98	* Execute complete transaction with the DB adapter
99	*
100	* @param  mixed $callable
101	* @param  mixed $params
102	* @throws \Exception
103	* @return void
104	*/
105	public function transaction(mixed $callable, mixed $params = null): void;
106
107	/**
108	* Check if transaction is success
109	*
110	* @return bool
111	*/
112	public function isSuccess(): bool;
113
114	/**
115	* Directly execute a SELECT SQL query or prepared statement and return the results
116	*
117	* @param  string|Sql $sql
118	* @param  array      $params
119	* @return array
120	*/
121	public function select(string|Sql $sql, array $params = []): array;
122
123	/**
124	* Directly execute an INSERT SQL query or prepared statement and return the results
125	*
126	* @param  string|Sql $sql
127	* @param  array      $params
128	* @return int
129	*/
130	public function insert(string|Sql $sql, array $params = []): int;
131
132	/**
133	* Directly execute an UPDATE SQL query or prepared statement and return the results
134	*
135	* @param  string|Sql $sql
136	* @param  array      $params
137	* @return int
138	*/
139	public function update(string|Sql $sql, array $params = []): int;
140
141	/**
142	* Directly execute a DELETE SQL query or prepared statement and return the results
143	*
144	* @param  string|Sql $sql
145	* @param  array      $params
146	* @return int
147	*/
148	public function delete(string|Sql $sql, array $params = []): int;
149
150	/**
151	* Execute a SQL query or prepared statement with params
152	*
153	* @param  string|Sql $sql
154	* @param  array $params
155	* @return AdapterInterface
156	*/
157	public function executeSql(string|Sql $sql, array $params = []): AdapterInterface;
158
159	/**
160	* Execute a SQL query directly
161	*
162	* @param  mixed $sql
163	* @return AdapterInterface
164	*/
165	public function query(mixed $sql): AdapterInterface;
166
167	/**
168	* Prepare a SQL query.
169	*
170	* @param  mixed $sql
171	* @return AdapterInterface
172	*/
173	public function prepare(mixed $sql): AdapterInterface;
174
175	/**
176	* Bind parameters to a prepared SQL query
177	*
178	* @param  array $params
179	* @return AdapterInterface
180	*/
181	public function bindParams(array $params): AdapterInterface;
182
183	/**
184	* Execute a prepared SQL query
185	*
186	* @return AdapterInterface
187	*/
188	public function execute(): AdapterInterface;
189
190	/**
191	* Fetch and return a row from the result
192	*
193	* @return mixed
194	*/
195	public function fetch(): mixed;
196
197	/**
198	* Fetch and return all rows from the result
199	*
200	* @return array
201	*/
202	public function fetchAll(): array;
203
204	/**
205	* Create SQL builder
206	*
207	* @return \Pop\Db\Sql
208	*/
209	public function createSql(): \Pop\Db\Sql;
210
211	/**
212	* Create Schema builder
213	*
214	* @return \Pop\Db\Sql\Schema
215	*/
216	public function createSchema(): \Pop\Db\Sql\Schema;
217
218	/**
219	* Determine whether or not connected
220	*
221	* @return bool
222	*/
223	public function isConnected(): bool;
224
225	/**
226	* Get the connection object/resource
227	*
228	* @return mixed
229	*/
230	public function getConnection(): mixed;
231
232	/**
233	* Determine whether or not a statement resource exists
234	*
235	* @return bool
236	*/
237	public function hasStatement(): bool;
238
239	/**
240	* Get the statement object/resource
241	*
242	* @return mixed
243	*/
244	public function getStatement(): mixed;
245
246	/**
247	* Determine whether or not a result resource exists
248	*
249	* @return bool
250	*/
251	public function hasResult(): bool;
252
253	/**
254	* Get the result object/resource
255	*
256	* @return mixed
257	*/
258	public function getResult(): mixed;
259
260	/**
261	* Add query listener to the adapter
262	*
263	* @param  mixed $listener
264	* @return mixed
265	*/
266	public function listen(mixed $listener): mixed;
267
268	/**
269	* Set query profiler
270	*
271	* @param  Profiler\Profiler $profiler
272	* @return AdapterInterface
273	*/
274	public function setProfiler(Profiler\Profiler $profiler): AdapterInterface;
275
276	/**
277	* Get query profiler
278	*
279	* @return Profiler\Profiler|null
280	*/
281	public function getProfiler(): Profiler\Profiler|null;
282
283	/**
284	* Clear query profiler
285	*
286	* @return AdapterInterface
287	*/
288	public function clearProfiler(): AdapterInterface;
289
290	/**
291	* Determine whether or not there is an error
292	*
293	* @return bool
294	*/
295	public function hasError(): bool;
296
297	/**
298	* Set the error
299	*
300	* @param  string $error
301	* @return AdapterInterface
302	*/
303	public function setError(string $error): AdapterInterface;
304
305	/**
306	* Get the error
307	*
308	* @return mixed
309	*/
310	public function getError(): mixed;
311
312	/**
313	* Throw a database error exception
314	*
315	* @throws Exception
316	* @return void
317	*/
318	public function throwError(): void;
319
320	/**
321	* Clear the error
322	*
323	* @return AdapterInterface
324	*/
325	public function clearError(): AdapterInterface;
326
327	/**
328	* Disconnect from the database
329	*
330	* @return void
331	*/
332	public function disconnect(): void;
333
334	/**
335	* Escape the value
336	*
337	* @param  ?string $value
338	* @return string
339	*/
340	public function escape(?string $value = null): string;
341
342	/**
343	* Return the last ID of the last query
344	*
345	* @return int
346	*/
347	public function getLastId(): int;
348
349	/**
350	* Return the number of rows from the last query
351	*
352	* @return int
353	*/
354	public function getNumberOfRows(): int;
355
356	/**
357	* Return the number of affected rows from the last query
358	*
359	* @return int
360	*/
361	public function getNumberOfAffectedRows(): int;
362
363	/**
364	* Return the database version
365	*
366	* @return string
367	*/
368	public function getVersion(): string;
369
370	/**
371	* Return the tables in the database
372	*
373	* @return array
374	*/
375	public function getTables(): array;
376
377	/**
378	* Return if the database has a table
379	*
380	* @param  string $table
381	* @return bool
382	*/
383	public function hasTable(string $table): bool;
384
385	}