[Summary view] [Print] [Text view]

   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  }