Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
n/a
0 / 0
n/a
0 / 0
CRAP
n/a
0 / 0
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
17namespace Query;
18
19use PDO;
20use 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 */
61interface 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