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 null
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        A SQL statement like "c1 = 'a' AND c2 = 'b'"
194	*/
195	public function sql_build_array($query, $assoc_ary = array());
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	* Gets the ID of the **last** inserted row immediately after an INSERT
293	* statement.
294	*
295	* **Note**: Despite the name, the returned ID refers to the row that has
296	* just been inserted, rather than the hypothetical ID of the next row if a
297	* new one was to be inserted.
298	*
299	* The returned value can be used for selecting the item that has just been
300	* inserted or for updating another table with an ID pointing to that item.
301	*
302	* Alias of `sql_last_inserted_id`.
303	*
304	* @deprecated 3.3.11-RC1 Replaced by sql_last_inserted_id(), to be removed in 4.1.0-a1
305	*
306	* @return    string|false    Auto-incremented value of the last inserted row
307	*/
308	public function sql_nextid();
309
310	/**
311	* Gets the ID of the last inserted row immediately after an INSERT
312	* statement. The returned value can be used for selecting the item that has
313	* just been inserted or for updating another table with an ID pointing to
314	* that item.
315	*
316	* @return    string|false    Auto-incremented value of the last inserted row
317	*/
318	public function sql_last_inserted_id();
319
320	/**
321	* Add to query count
322	*
323	* @param bool $cached    Is this query cached?
324	* @return null
325	*/
326	public function sql_add_num_queries($cached = false);
327
328	/**
329	* Build LIMIT query
330	*
331	* @param    string    $query        The SQL query to execute
332	* @param    int        $total        The number of rows to select
333	* @param    int        $offset
334	* @param    int        $cache_ttl    Either 0 to avoid caching or
335	*                the time in seconds which the result shall be kept in cache
336	* @return    mixed    Buffered, seekable result handle, false on error
337	*/
338	public function sql_query_limit($query, $total, $offset = 0, $cache_ttl = 0);
339
340	/**
341	* Base query method
342	*
343	* @param    string    $query        The SQL query to execute
344	* @param    int        $cache_ttl    Either 0 to avoid caching or
345	*                the time in seconds which the result shall be kept in cache
346	* @return    mixed    Buffered, seekable result handle, false on error
347	*/
348	public function sql_query($query = '', $cache_ttl = 0);
349
350	/**
351	* Returns SQL string to cast an integer expression to a string.
352	*
353	* @param    string    $expression        An expression evaluating to int
354	* @return string        Expression returning a string
355	*/
356	public function cast_expr_to_string($expression);
357
358	/**
359	* Connect to server
360	*
361	* @param    string    $sqlserver        Address of the database server
362	* @param    string    $sqluser        User name of the SQL user
363	* @param    string    $sqlpassword    Password of the SQL user
364	* @param    string    $database        Name of the database
365	* @param    mixed    $port            Port of the database server
366	* @param    bool    $persistency
367	* @param    bool    $new_link        Should a new connection be established
368	* @return    mixed    Connection ID on success, string error message otherwise
369	*/
370	public function sql_connect($sqlserver, $sqluser, $sqlpassword, $database, $port = false, $persistency = false, $new_link = false);
371
372	/**
373	* Run binary AND operator on DB column.
374	* Results in sql statement: "{$column_name} & (1 << {$bit}) {$compare}"
375	*
376	* @param string    $column_name    The column name to use
377	* @param int    $bit            The value to use for the AND operator,
378	*                                will be converted to (1 << $bit). Is used by
379	*                                options, using the number schema: 0, 1, 2...29
380	* @param string    $compare        Any custom SQL code after the check (for example "= 0")
381	* @return string    A SQL statement like: "{$column} & (1 << {$bit}) {$compare}"
382	*/
383	public function sql_bit_and($column_name, $bit, $compare = '');
384
385	/**
386	* Free sql result
387	*
388	* @param    mixed    $query_id    Already executed query result,
389	*                                if false, the last query will be used.
390	* @return    null
391	*/
392	public function sql_freeresult($query_id = false);
393
394	/**
395	* Return number of sql queries and cached sql queries used
396	*
397	* @param    bool    $cached        Should we return the number of cached or normal queries?
398	* @return    int        Number of queries that have been executed
399	*/
400	public function sql_num_queries($cached = false);
401
402	/**
403	* Run more than one insert statement.
404	*
405	* @param string    $table        Table name to run the statements on
406	* @param array    $sql_ary    Multi-dimensional array holding the statement data
407	* @return bool        false if no statements were executed.
408	*/
409	public function sql_multi_insert($table, $sql_ary);
410
411	/**
412	* Return number of affected rows
413	*
414	* @return    mixed        Number of the affected rows by the last query
415	*                        false if no query has been run before
416	*/
417	public function sql_affectedrows();
418
419	/**
420	* DBAL garbage collection, close SQL connection
421	*
422	* @return    mixed        False if no connection was opened before,
423	*                        Server response otherwise
424	*/
425	public function sql_close();
426
427	/**
428	* Seek to given row number
429	*
430	* @param    mixed    $rownum        Row number the curser should point to
431	*                                Note: $rownum is 0 based
432	* @param    mixed    $query_id    ID of the query to set the row cursor on
433	*                                if false, the last query will be used.
434	*                                $query_id will then be set correctly
435	* @return    bool        False if something went wrong
436	*/
437	public function sql_rowseek($rownum, &$query_id);
438
439	/**
440	* Escape string used in sql query
441	*
442	* @param    string    $msg    String to be escaped
443	* @return    string        Escaped version of $msg
444	*/
445	public function sql_escape($msg);
446
447	/**
448	* Correctly adjust LIKE expression for special characters
449	* Some DBMS are handling them in a different way
450	*
451	* @param    string    $expression    The expression to use. Every wildcard is
452	*                        escaped, except $this->any_char and $this->one_char
453	* @return string    A SQL statement like: "LIKE 'bertie_%'"
454	*/
455	public function sql_like_expression($expression);
456
457	/**
458	* Correctly adjust NOT LIKE expression for special characters
459	* Some DBMS are handling them in a different way
460	*
461	* @param    string    $expression    The expression to use. Every wildcard is
462	*                        escaped, except $this->any_char and $this->one_char
463	* @return string    A SQL statement like: "NOT LIKE 'bertie_%'"
464	*/
465	public function sql_not_like_expression($expression);
466
467	/**
468	* Explain queries
469	*
470	* @param    string    $mode        Available modes: display, start, stop,
471	*                                add_select_row, fromcache, record_fromcache
472	* @param    string    $query        The Query that should be explained
473	* @return    mixed        Either a full HTML page, boolean or null
474	*/
475	public function sql_report($mode, $query = '');
476
477	/**
478	* Build IN or NOT IN sql comparison string, uses <> or = on single element
479	* arrays to improve comparison speed
480	*
481	* @param    string    $field            Name of the sql column that shall be compared
482	* @param    array    $array            Array of values that are (not) allowed
483	* @param    bool    $negate            true for NOT IN (), false for IN ()
484	* @param    bool    $allow_empty_set    If true, allow $array to be empty,
485	*                                this function will return 1=1 or 1=0 then.
486	* @return string    A SQL statement like: "IN (1, 2, 3, 4)" or "= 1"
487	*/
488	public function sql_in_set($field, $array, $negate = false, $allow_empty_set = false);
489
490	/**
491	* Quote identifiers used in sql query
492	*
493	* @param    string    $msg    String to be quoted
494	* @return    string        Quoted version of $msg
495	*/
496	public function sql_quote($msg);
497
498	/**
499	* Ensure query ID can be used by cache
500	*
501	* @param resource|int|string $query_id Mixed type query id
502	*
503	* @return int|string Query id in string or integer format
504	*/
505	public function clean_query_id($query_id);
506	}