1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\db\driver;
15
16	interface driver_interface
17	{
18	/**
19	* Set value for load_time debug parameter
20	*
21	* @param bool $value
22	*/
23	public function set_debug_load_time($value);
24
25	/**
26	* Set value for sql_explain debug parameter
27	*
28	* @param bool $value
29	*/
30	public function set_debug_sql_explain($value);
31
32	/**
33	* Gets the name of the sql layer.
34	*
35	* @return string
36	*/
37	public function get_sql_layer();
38
39	/**
40	* Gets the name of the database.
41	*
42	* @return string
43	*/
44	public function get_db_name();
45
46	/**
47	* Wildcards for matching any (%) character within LIKE expressions
48	*
49	* @return string
50	*/
51	public function get_any_char();
52
53	/**
54	* Wildcards for matching exactly one (_) character within LIKE expressions
55	*
56	* @return string
57	*/
58	public function get_one_char();
59
60	/**
61	* Gets the time spent into the queries
62	*
63	* @return int
64	*/
65	public function get_sql_time();
66
67	/**
68	* Gets the connect ID.
69	*
70	* @return mixed
71	*/
72	public function get_db_connect_id();
73
74	/**
75	* Indicates if an error was triggered.
76	*
77	* @return bool
78	*/
79	public function get_sql_error_triggered();
80
81	/**
82	* Gets the last faulty query
83	*
84	* @return string
85	*/
86	public function get_sql_error_sql();
87
88	/**
89	* Indicates if we are in a transaction.
90	*
91	* @return bool
92	*/
93	public function get_transaction();
94
95	/**
96	* Gets the returned error.
97	*
98	* @return array
99	*/
100	public function get_sql_error_returned();
101
102	/**
103	* Indicates if multiple insertion can be used
104	*
105	* @return bool
106	*/
107	public function get_multi_insert();
108
109	/**
110	* Set if multiple insertion can be used
111	*
112	* @param bool $multi_insert
113	*/
114	public function set_multi_insert($multi_insert);
115
116	/**
117	* Gets the exact number of rows in a specified table.
118	*
119	* @param string $table_name Table name
120	* @return string    Exact number of rows in $table_name.
121	*/
122	public function get_row_count($table_name);
123
124	/**
125	* Gets the estimated number of rows in a specified table.
126	*
127	* @param string $table_name Table name
128	* @return string    Number of rows in $table_name.
129	*                    Prefixed with ~ if estimated (otherwise exact).
130	*/
131	public function get_estimated_row_count($table_name);
132
133	/**
134	* Run LOWER() on DB column of type text (i.e. neither varchar nor char).
135	*
136	* @param string $column_name    The column name to use
137	* @return string        A SQL statement like "LOWER($column_name)"
138	*/
139	public function sql_lower_text($column_name);
140
141	/**
142	* Display sql error page
143	*
144	* @param string        $sql    The SQL query causing the error
145	* @return mixed        Returns the full error message, if $this->return_on_error
146	*                    is set, null otherwise
147	*/
148	public function sql_error($sql = '');
149
150	/**
151	* Returns whether results of a query need to be buffered to run a
152	* transaction while iterating over them.
153	*
154	* @return bool    Whether buffering is required.
155	*/
156	public function sql_buffer_nested_transactions();
157
158	/**
159	* Run binary OR operator on DB column.
160	*
161	* @param string    $column_name    The column name to use
162	* @param int    $bit            The value to use for the OR operator,
163	*                    will be converted to (1 << $bit). Is used by options,
164	*                    using the number schema... 0, 1, 2...29
165	* @param string    $compare    Any custom SQL code after the check (e.g. "= 0")
166	* @return string    A SQL statement like "$column | (1 << $bit) {$compare}"
167	*/
168	public function sql_bit_or($column_name, $bit, $compare = '');
169
170	/**
171	* Version information about used database
172	*
173	* @param bool $raw            Only return the fetched sql_server_version
174	* @param bool $use_cache    Is it safe to retrieve the value from the cache
175	* @return string sql server version
176	*/
177	public function sql_server_info($raw = false, $use_cache = true);
178
179	/**
180	* Return on error or display error message
181	*
182	* @param bool    $fail        Should we return on errors, or stop
183	* @return void
184	*/
185	public function sql_return_on_error($fail = false);
186
187	/**
188	* Build sql statement from an array
189	*
190	* @param    string    $query        Should be on of the following strings:
191	*                        INSERT, INSERT_SELECT, UPDATE, SELECT, DELETE
192	* @param    array    $assoc_ary    Array with "column => value" pairs
193	* @return    string|false        A SQL statement like "c1 = 'a' AND c2 = 'b'", false on invalid assoc_ary
194	*/
195	public function sql_build_array($query, $assoc_ary = []);
196
197	/**
198	* Fetch all rows
199	*
200	* @param    mixed    $query_id    Already executed query to get the rows from,
201	*                                if false, the last query will be used.
202	* @return    mixed        Nested array if the query had rows, false otherwise
203	*/
204	public function sql_fetchrowset($query_id = false);
205
206	/**
207	* SQL Transaction
208	*
209	* @param    string    $status        Should be one of the following strings:
210	*                                begin, commit, rollback
211	* @return    mixed    Buffered, seekable result handle, false on error
212	*/
213	public function sql_transaction($status = 'begin');
214
215	/**
216	* Build a concatenated expression
217	*
218	* @param    string    $expr1        Base SQL expression where we append the second one
219	* @param    string    $expr2        SQL expression that is appended to the first expression
220	* @return    string        Concatenated string
221	*/
222	public function sql_concatenate($expr1, $expr2);
223
224	/**
225	* Build a case expression
226	*
227	* Note: The two statements action_true and action_false must have the same
228	* data type (int, vchar, ...) in the database!
229	*
230	* @param    string    $condition        The condition which must be true,
231	*                            to use action_true rather then action_else
232	* @param    string    $action_true    SQL expression that is used, if the condition is true
233	* @param    mixed    $action_false    SQL expression that is used, if the condition is false
234	* @return    string        CASE expression including the condition and statements
235	*/
236	public function sql_case($condition, $action_true, $action_false = false);
237
238	/**
239	* Build sql statement from array for select and select distinct statements
240	*
241	* Possible query values: SELECT, SELECT_DISTINCT
242	*
243	* @param    string    $query    Should be one of: SELECT, SELECT_DISTINCT
244	* @param    array    $array    Array with the query data:
245	*                    SELECT        A comma imploded list of columns to select
246	*                    FROM        Array with "table => alias" pairs,
247	*                                (alias can also be an array)
248	*        Optional:    LEFT_JOIN    Array of join entries:
249	*                        FROM        Table that should be joined
250	*                        ON            Condition for the join
251	*        Optional:    WHERE        Where SQL statement
252	*        Optional:    GROUP_BY    Group by SQL statement
253	*        Optional:    ORDER_BY    Order by SQL statement
254	* @return    string        A SQL statement ready for execution
255	*/
256	public function sql_build_query($query, $array);
257
258	/**
259	* Fetch field
260	* if rownum is false, the current row is used, else it is pointing to the row (zero-based)
261	*
262	* @param    string    $field        Name of the column
263	* @param    mixed    $rownum        Row number, if false the current row will be used
264	*                                and the row curser will point to the next row
265	*                                Note: $rownum is 0 based
266	* @param    mixed    $query_id    Already executed query to get the rows from,
267	*                                if false, the last query will be used.
268	* @return    mixed        String value of the field in the selected row,
269	*                        false, if the row does not exist
270	*/
271	public function sql_fetchfield($field, $rownum = false, &$query_id = false);
272
273	/**
274	* Fetch current row
275	*
276	* @param    mixed    $query_id    Already executed query to get the rows from,
277	*                                if false, the last query will be used.
278	* @return    mixed        Array with the current row,
279	*                        false, if the row does not exist
280	*/
281	public function sql_fetchrow($query_id = false);
282
283	/**
284	* Returns SQL string to cast a string expression to an int.
285	*
286	* @param  string $expression An expression evaluating to string
287	* @return string             Expression returning an int
288	*/
289	public function cast_expr_to_bigint($expression);
290
291	/**
292
293	* Gets the ID of the **last** inserted row immediately after an INSERT
294	* statement.
295	*
296	* **Note**: Despite the name, the returned ID refers to the row that has
297	* just been inserted, rather than the hypothetical ID of the next row if a
298	* new one was to be inserted.
299	*
300	* The returned value can be used for selecting the item that has just been
301	* inserted or for updating another table with an ID pointing to that item.
302	*
303	* Alias of `sql_last_inserted_id`.
304	*
305	* @deprecated 3.3.11-RC1 Replaced by sql_last_inserted_id(), to be removed in 4.1.0-a1
306	*
307	* @return    int|false    Auto-incremented value of the last inserted row
308	*/
309	public function sql_nextid();
310
311	/**
312	* Gets the ID of the last inserted row immediately after an INSERT
313	* statement. The returned value can be used for selecting the item that has
314	* just been inserted or for updating another table with an ID pointing to
315	* that item.
316	*
317	* @return    int|false    Auto-incremented value of the last inserted row
318	*/
319	public function sql_last_inserted_id();
320
321	/**
322	* Add to query count
323	*
324	* @param bool $cached    Is this query cached?
325	* @return void
326	*/
327	public function sql_add_num_queries($cached = false);
328
329	/**
330	* Build LIMIT query
331	*
332	* @param    string    $query        The SQL query to execute
333	* @param    int        $total        The number of rows to select
334	* @param    int        $offset
335	* @param    int        $cache_ttl    Either 0 to avoid caching or
336	*                the time in seconds which the result shall be kept in cache
337	* @return    mixed    Buffered, seekable result handle, false on error
338	*/
339	public function sql_query_limit($query, $total, $offset = 0, $cache_ttl = 0);
340
341	/**
342	* Base query method
343	*
344	* @param    string    $query        The SQL query to execute
345	* @param    int        $cache_ttl    Either 0 to avoid caching or
346	*                the time in seconds which the result shall be kept in cache
347	* @return    mixed    Buffered, seekable result handle, false on error
348	*/
349	public function sql_query($query = '', $cache_ttl = 0);
350
351	/**
352	* Returns SQL string to cast an integer expression to a string.
353	*
354	* @param    string    $expression        An expression evaluating to int
355	* @return string        Expression returning a string
356	*/
357	public function cast_expr_to_string($expression);
358
359	/**
360	* Connect to server
361	*
362	* @param    string    $sqlserver        Address of the database server
363	* @param    string    $sqluser        User name of the SQL user
364	* @param    string    $sqlpassword    Password of the SQL user
365	* @param    string    $database        Name of the database
366	* @param    mixed    $port            Port of the database server
367	* @param    bool    $persistency
368	* @param    bool    $new_link        Should a new connection be established
369	* @return    mixed    Connection ID on success, string error message otherwise
370	*/
371	public function sql_connect($sqlserver, $sqluser, $sqlpassword, $database, $port = false, $persistency = false, $new_link = false);
372
373	/**
374	* Run binary AND operator on DB column.
375	* Results in sql statement: "{$column_name} & (1 << {$bit}) {$compare}"
376	*
377	* @param string    $column_name    The column name to use
378	* @param int    $bit            The value to use for the AND operator,
379	*                                will be converted to (1 << $bit). Is used by
380	*                                options, using the number schema: 0, 1, 2...29
381	* @param string    $compare        Any custom SQL code after the check (for example "= 0")
382	* @return string    A SQL statement like: "{$column} & (1 << {$bit}) {$compare}"
383	*/
384	public function sql_bit_and($column_name, $bit, $compare = '');
385
386	/**
387	* Free sql result
388	*
389	* @param    mixed    $query_id    Already executed query result,
390	*                                if false, the last query will be used.
391	* @return    void
392	*/
393	public function sql_freeresult($query_id = false);
394
395	/**
396	* Return number of sql queries and cached sql queries used
397	*
398	* @param    bool    $cached        Should we return the number of cached or normal queries?
399	* @return    int        Number of queries that have been executed
400	*/
401	public function sql_num_queries($cached = false);
402
403	/**
404	* Run more than one insert statement.
405	*
406	* @param string    $table        Table name to run the statements on
407	* @param array    $sql_ary    Multi-dimensional array holding the statement data
408	* @return bool        false if no statements were executed.
409	*/
410	public function sql_multi_insert($table, $sql_ary);
411
412	/**
413	* Return number of affected rows
414	*
415	* @return    mixed        Number of the affected rows by the last query
416	*                        false if no query has been run before
417	*/
418	public function sql_affectedrows();
419
420	/**
421	* DBAL garbage collection, close SQL connection
422	*
423	* @return    mixed        False if no connection was opened before,
424	*                        Server response otherwise
425	*/
426	public function sql_close();
427
428	/**
429	* Seek to given row number
430	*
431	* @param    mixed    $rownum        Row number the curser should point to
432	*                                Note: $rownum is 0 based
433	* @param    mixed    $query_id    ID of the query to set the row cursor on
434	*                                if false, the last query will be used.
435	*                                $query_id will then be set correctly
436	* @return    bool        False if something went wrong
437	*/
438	public function sql_rowseek($rownum, &$query_id);
439
440	/**
441	* Escape string used in sql query
442	*
443	* @param    string    $msg    String to be escaped
444	* @return    string        Escaped version of $msg
445	*/
446	public function sql_escape($msg);
447
448	/**
449	* Correctly adjust LIKE expression for special characters
450	* Some DBMS are handling them in a different way
451	*
452	* @param    string    $expression    The expression to use. Every wildcard is
453	*                        escaped, except $this->any_char and $this->one_char
454	* @return string    A SQL statement like: "LIKE 'bertie_%'"
455	*/
456	public function sql_like_expression($expression);
457
458	/**
459	* Correctly adjust NOT LIKE expression for special characters
460	* Some DBMS are handling them in a different way
461	*
462	* @param    string    $expression    The expression to use. Every wildcard is
463	*                        escaped, except $this->any_char and $this->one_char
464	* @return string    A SQL statement like: "NOT LIKE 'bertie_%'"
465	*/
466	public function sql_not_like_expression($expression);
467
468	/**
469	* Explain queries
470	*
471	* @param    string    $mode        Available modes: display, start, stop,
472	*                                add_select_row, fromcache, record_fromcache
473	* @param    string    $query        The Query that should be explained
474	* @return    mixed        Either a full HTML page, boolean or null
475	*/
476	public function sql_report($mode, $query = '');
477
478	/**
479	* Build IN or NOT IN sql comparison string, uses <> or = on single element
480	* arrays to improve comparison speed
481	*
482	* @param    string    $field            Name of the sql column that shall be compared
483	* @param    array    $array            Array of values that are (not) allowed
484	* @param    bool    $negate            true for NOT IN (), false for IN ()
485	* @param    bool    $allow_empty_set    If true, allow $array to be empty,
486	*                                this function will return 1=1 or 1=0 then.
487	* @return string    A SQL statement like: "IN (1, 2, 3, 4)" or "= 1"
488	*/
489	public function sql_in_set($field, $array, $negate = false, $allow_empty_set = false);
490
491	/**
492	* Quote identifiers used in sql query
493	*
494	* @param    string    $msg    String to be quoted
495	* @return    string        Quoted version of $msg
496	*/
497	public function sql_quote($msg);
498
499	/**
500	* Ensure query ID can be used by cache
501	*
502	* @param mixed $query_id Mixed type query id
503	*
504	* @return int|string|null Query id in string or integer format
505	*/
506	public function clean_query_id(mixed $query_id): int|string|null;
507	}