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