1	<?php declare(strict_types=1);
2	/**
3	* Query
4	*
5	* SQL Query Builder / Database Abstraction Layer
6	*
7	* PHP version 8.1
8	*
9	* @package     Query
10	* @author      Timothy J. Warren <tim@timshome.page>
11	* @copyright   2012 - 2023 Timothy J. Warren
12	* @license     http://www.opensource.org/licenses/mit-license.html  MIT License
13	* @link        https://git.timshomepage.net/aviat/Query
14	* @version     4.0.0
15	*/
16
17	namespace Query;
18
19	use PDO;
20	use PDOStatement;
21
22	/**
23	* Interface defining the Query Builder class
24	*
25	* @method affectedRows(): int
26	* @method beginTransaction(): bool
27	* @method commit(): bool
28	* @method errorCode(): string
29	* @method errorInfo(): array
30	* @method exec(string $statement): int
31	* @method getAttribute(int $attribute)
32	* @method getColumns(string $table): array | null
33	* @method getDbs(): array | null
34	* @method getFks(string $table): array | null
35	* @method getFunctions(): array | null
36	* @method getIndexes(string $table): array | null
37	* @method getLastQuery(): string
38	* @method getProcedures(): array | null
39	* @method getSchemas(): array | null
40	* @method getSequences(): array | null
41	* @method getSystemTables(): array | null
42	* @method getTables(): array
43	* @method getTriggers(): array | null
44	* @method getTypes(): array | null
45	* @method getUtil(): \Query\Drivers\AbstractUtil
46	* @method getVersion(): string
47	* @method getViews(): array | null
48	* @method inTransaction(): bool
49	* @method lastInsertId(string $name = NULL): string
50	* @method numRows(): int | null
51	* @method prepare(string $statement, array $driver_options = []): PDOStatement
52	* @method prepareExecute(string $sql, array $params): PDOStatement
53	* @method prepareQuery(string $sql, array $data): PDOStatement
54	* @method query(string $statement): PDOStatement
55	* @method quote(string $string, int $parameter_type = PDO::PARAM_STR): string
56	* @method rollback(): bool
57	* @method setAttribute(int $attribute, $value): bool
58	* @method setTablePrefix(string $prefix): void
59	* @method truncate(string $table): PDOStatement
60	*/
61	interface QueryBuilderInterface
62	{
63	// --------------------------------------------------------------------------
64	// ! Select Queries
65	// --------------------------------------------------------------------------
66	/**
67	* Specifies rows to select in a query
68	*/
69	public function select(string $fields): self;
70
71	/**
72	* Selects the maximum value of a field from a query
73	*
74	* @param bool|string $as
75	*/
76	public function selectMax(string $field, $as=FALSE): self;
77
78	/**
79	* Selects the minimum value of a field from a query
80	*
81	* @param bool|string $as
82	*/
83	public function selectMin(string $field, $as=FALSE): self;
84
85	/**
86	* Selects the average value of a field from a query
87	*
88	* @param bool|string $as
89	*/
90	public function selectAvg(string $field, $as=FALSE): self;
91
92	/**
93	* Selects the sum of a field from a query
94	*
95	* @param bool|string $as
96	*/
97	public function selectSum(string $field, $as=FALSE): self;
98
99	/**
100	* Adds the 'distinct' keyword to a query
101	*/
102	public function distinct(): self;
103
104	/**
105	* Shows the query plan for the query
106	*/
107	public function explain(): self;
108
109	/**
110	* Specify the database table to select from
111	*
112	* Alias of `from` method to better match CodeIgniter 4
113	*/
114	public function table(string $tableName): self;
115
116	/**
117	* Specify the database table to select from
118	*/
119	public function from(string $tableName): self;
120
121	// --------------------------------------------------------------------------
122	// ! 'Like' methods
123	// --------------------------------------------------------------------------
124	/**
125	* Creates a Like clause in the sql statement
126	*/
127	public function like(string $field, mixed $values, LikeType|string $pos=LikeType::BOTH): self;
128
129	/**
130	* Generates an OR Like clause
131	*/
132	public function orLike(string $field, mixed $values, LikeType|string $pos=LikeType::BOTH): self;
133
134	/**
135	* Generates a NOT LIKE clause
136	*/
137	public function notLike(string $field, mixed $values, LikeType|string $pos=LikeType::BOTH): self;
138
139	/**
140	* Generates a OR NOT LIKE clause
141	*/
142	public function orNotLike(string $field, mixed $values, LikeType|string $pos=LikeType::BOTH): self;
143
144	// --------------------------------------------------------------------------
145	// ! Having methods
146	// --------------------------------------------------------------------------
147	/**
148	* Generates a 'Having' clause
149	*/
150	public function having(mixed $key, mixed $values=[]): self;
151
152	/**
153	* Generates a 'Having' clause prefixed with 'OR'
154	*/
155	public function orHaving(mixed $key, mixed $values=[]): self;
156
157	// --------------------------------------------------------------------------
158	// ! 'Where' methods
159	// --------------------------------------------------------------------------
160	/**
161	* Specify condition(s) in the where clause of a query
162	* Note: this function works with key / value, or a
163	* passed array with key / value pairs
164	*/
165	public function where(mixed $key, mixed $values=[]): self;
166
167	/**
168	* Where clause prefixed with "OR"
169	*
170	* @param string $key
171	*/
172	public function orWhere(mixed $key, mixed $values=[]): self;
173
174	/**
175	* Where clause with 'IN' statement
176	*/
177	public function whereIn(string $field, mixed $values=[]): self;
178
179	/**
180	* Where in statement prefixed with "or"
181	*/
182	public function orWhereIn(string $field, mixed $values=[]): self;
183
184	/**
185	* WHERE NOT IN (FOO) clause
186	*/
187	public function whereNotIn(string $field, mixed $values=[]): self;
188
189	/**
190	* OR WHERE NOT IN (FOO) clause
191	*/
192	public function orWhereNotIn(string $field, mixed $values=[]): self;
193
194	// --------------------------------------------------------------------------
195	// ! Other Query Modifier methods
196	// --------------------------------------------------------------------------
197	/**
198	* Sets values for inserts / updates / deletes
199	*
200	* @param mixed $values
201	*/
202	public function set(mixed $key, mixed $values = NULL): self;
203
204	/**
205	* Creates a join phrase in a compiled query
206	*/
207	public function join(string $table, string $condition, JoinType|string $type=JoinType::INNER): self;
208
209	/**
210	* Group the results by the selected field(s)
211	*/
212	public function groupBy(mixed $field): self;
213
214	/**
215	* Order the results by the selected field(s)
216	*/
217	public function orderBy(string $field, string $type=''): self;
218
219	/**
220	* Set a limit on the current sql statement
221	*/
222	public function limit(int $limit, ?int $offset=NULL): self;
223
224	// --------------------------------------------------------------------------
225	// ! Query Grouping Methods
226	// --------------------------------------------------------------------------
227	/**
228	* Adds a paren to the current query for query grouping
229	*/
230	public function groupStart(): self;
231
232	/**
233	* Adds a paren to the current query for query grouping,
234	* prefixed with 'NOT'
235	*/
236	public function notGroupStart(): self;
237
238	/**
239	* Adds a paren to the current query for query grouping,
240	* prefixed with 'OR'
241	*/
242	public function orGroupStart(): self;
243
244	/**
245	* Adds a paren to the current query for query grouping,
246	* prefixed with 'OR NOT'
247	*/
248	public function orNotGroupStart(): self;
249
250	/**
251	* Ends a query group
252	*/
253	public function groupEnd(): self;
254
255	// --------------------------------------------------------------------------
256	// ! Query execution methods
257	// --------------------------------------------------------------------------
258	/**
259	* Select and retrieve all records from the current table, and/or
260	* execute current compiled query
261	*/
262	public function get(string $table='', ?int $limit=NULL, ?int $offset=NULL): PDOStatement;
263
264	/**
265	* Convenience method for get() with a where clause
266	*/
267	public function getWhere(string $table, array $where=[], ?int $limit=NULL, ?int $offset=NULL): PDOStatement;
268
269	/**
270	* Retrieve the number of rows in the selected table
271	*/
272	public function countAll(string $table): int;
273
274	/**
275	* Retrieve the number of results for the generated query - used
276	* in place of the get() method
277	*
278	* @param bool $reset - Whether to keep the query after counting the results
279	*/
280	public function countAllResults(string $table='', bool $reset=TRUE): int;
281
282	/**
283	* Creates an insert clause, and executes it
284	*/
285	public function insert(string $table, mixed $data=[]): PDOStatement;
286
287	/**
288	* Creates and executes a batch insertion query
289	*
290	* @param array $data
291	*/
292	public function insertBatch(string $table, mixed $data=[]): ?PDOStatement;
293
294	/**
295	* Creates an update clause, and executes it
296	*/
297	public function update(string $table, mixed $data=[]): PDOStatement;
298
299	/**
300	* Creates a batch update, and executes it.
301	* Returns the number of affected rows
302	*
303	* @param string $table The table to update
304	* @param array $data an array of update values
305	* @param string $where The where key
306	*/
307	public function updateBatch(string $table, array $data, string $where): ?int;
308
309	/**
310	* Deletes data from a table
311	*/
312	public function delete(string $table, mixed $where=''): PDOStatement;
313
314	// --------------------------------------------------------------------------
315	// ! SQL Returning Methods
316	// --------------------------------------------------------------------------
317	/**
318	* Returns the generated 'select' sql query
319	*/
320	public function getCompiledSelect(string $table='', bool $reset=TRUE): string;
321
322	/**
323	* Returns the generated 'insert' sql query
324	*/
325	public function getCompiledInsert(string $table, bool $reset=TRUE): string;
326
327	/**
328	* Returns the generated 'update' sql query
329	*/
330	public function getCompiledUpdate(string $table='', bool $reset=TRUE): string;
331
332	/**
333	* Returns the generated 'delete' sql query
334	*/
335	public function getCompiledDelete(string $table='', bool $reset=TRUE): string;
336
337	// --------------------------------------------------------------------------
338	// ! Miscellaneous Methods
339	// --------------------------------------------------------------------------
340	/**
341	* Clear out the class variables, so the next query can be run
342	*/
343	public function resetQuery(): void;
344	}
345
346	// End of QueryBuilderInterface.php