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