abstract class driver implements driver_interface

Database Abstraction Layer

Constants

LOGICAL_OP

STATEMENTS

LEFT_STMT

COMPARE_OP

RIGHT_STMT

SUBQUERY_OP

SUBQUERY_SELECT_TYPE

SUBQUERY_BUILD

Properties

$db_connect_id
$query_result
$return_on_error
$transaction
$sql_time
$num_queries
$open_queries
$curtime
$query_hold
$html_hold
$sql_report
$persistency
$user
$server
$dbname
$sql_error_triggered
$sql_error_sql
$sql_error_returned
$transactions
$multi_insert
$sql_layer

Current sql layer

$any_char

Wildcards for matching any (%) or exactly one (_) character within LIKE expressions

$one_char
$sql_server_version

Exact version of the DBAL, directly queried

protected bool $debug_load_time
protected bool $debug_sql_explain

Methods

__construct()

Constructor

set_debug_load_time(bool $value)

Set value for load_time debug parameter

set_debug_sql_explain(bool $value)

Set value for sql_explain debug parameter

string
get_sql_layer()

Gets the name of the sql layer.

string
get_db_name()

Gets the name of the database.

string
get_any_char()

Wildcards for matching any (%) character within LIKE expressions

string
get_one_char()

Wildcards for matching exactly one (_) character within LIKE expressions

mixed
get_db_connect_id()

Gets the connect ID.

bool
get_sql_error_triggered()

Indicates if an error was triggered.

string
get_sql_error_sql()

Gets the last faulty query

bool
get_transaction()

Indicates if we are in a transaction.

int
get_sql_time()

Gets the time spent into the queries

array
get_sql_error_returned()

Gets the returned error.

bool
get_multi_insert()

Indicates if multiple insertion can be used

set_multi_insert(bool $multi_insert)

Set if multiple insertion can be used

null
sql_return_on_error(bool $fail = false)

Return on error or display error message

int
sql_num_queries(bool $cached = false)

Return number of sql queries and cached sql queries used

null
sql_add_num_queries(bool $cached = false)

Add to query count

mixed
sql_close()

DBAL garbage collection, close SQL connection

mixed
sql_query_limit(string $query, int $total, int $offset = 0, int $cache_ttl = 0)

Build LIMIT query

mixed
sql_fetchrowset(mixed $query_id = false)

Fetch all rows

bool
sql_rowseek(mixed $rownum, mixed $query_id)

Seek to given row number

mixed
sql_fetchfield(string $field, mixed $rownum = false, mixed $query_id = false)

Fetch field if rownum is false, the current row is used, else it is pointing to the row (zero-based)

string
sql_like_expression(string $expression)

Correctly adjust LIKE expression for special characters Some DBMS are handling them in a different way

string
sql_not_like_expression(string $expression)

Correctly adjust NOT LIKE expression for special characters Some DBMS are handling them in a different way

string
sql_case(string $condition, string $action_true, mixed $action_false = false)

Build a case expression

string
sql_concatenate(string $expr1, string $expr2)

Build a concatenated expression

bool
sql_buffer_nested_transactions()

Returns whether results of a query need to be buffered to run a transaction while iterating over them.

mixed
sql_transaction(string $status = 'begin')

SQL Transaction

string
sql_build_array(string $query, array $assoc_ary = false)

Build sql statement from an array

string
sql_in_set(string $field, array $array, bool $negate = false, bool $allow_empty_set = false)

Build IN or NOT IN sql comparison string, uses <> or = on single element arrays to improve comparison speed

string
sql_bit_and(string $column_name, int $bit, string $compare = '')

Run binary AND operator on DB column.

string
sql_bit_or(string $column_name, int $bit, string $compare = '')

Run binary OR operator on DB column.

string
cast_expr_to_bigint(string $expression)

Returns SQL string to cast a string expression to an int.

string|false
sql_nextid()

Gets the ID of the last inserted row immediately after an INSERT statement.

string
cast_expr_to_string(string $expression)

Returns SQL string to cast an integer expression to a string.

string
sql_lower_text(string $column_name)

Run LOWER() on DB column of type text (i.e. neither varchar nor char).

bool
sql_multi_insert(string $table, array $sql_ary)

Run more than one insert statement.

string
sql_build_query(string $query, array $array)

Build sql statement from array for select and select distinct statements

_process_boolean_tree_first($operations_ary)

No description

_process_boolean_tree($operations_ary)

No description

mixed
sql_error(string $sql = '')

Display sql error page

mixed
sql_report(string $mode, string $query = '')

Explain queries

string
get_estimated_row_count(string $table_name)

Gets the estimated number of rows in a specified table.

string
get_row_count(string $table_name)

Gets the exact number of rows in a specified table.

int|string
clean_query_id(resource|int|string $query_id)

Ensure query ID can be used by cache

Details

at line 91
__construct()

Constructor

at line 111
set_debug_load_time(bool $value)

Set value for load_time debug parameter

Parameters

bool $value

at line 119
set_debug_sql_explain(bool $value)

Set value for sql_explain debug parameter

Parameters

bool $value

at line 127
string get_sql_layer()

Gets the name of the sql layer.

Return Value

string

at line 135
string get_db_name()

Gets the name of the database.

Return Value

string

at line 143
string get_any_char()

Wildcards for matching any (%) character within LIKE expressions

Return Value

string

at line 151
string get_one_char()

Wildcards for matching exactly one (_) character within LIKE expressions

Return Value

string

at line 159
mixed get_db_connect_id()

Gets the connect ID.

Return Value

mixed

at line 167
bool get_sql_error_triggered()

Indicates if an error was triggered.

Return Value

bool

at line 175
string get_sql_error_sql()

Gets the last faulty query

Return Value

string

at line 183
bool get_transaction()

Indicates if we are in a transaction.

Return Value

bool

at line 191
int get_sql_time()

Gets the time spent into the queries

Return Value

int

at line 199
array get_sql_error_returned()

Gets the returned error.

Return Value

array

at line 207
bool get_multi_insert()

Indicates if multiple insertion can be used

Return Value

bool

at line 215
set_multi_insert(bool $multi_insert)

Set if multiple insertion can be used

Parameters

bool $multi_insert

at line 223
null sql_return_on_error(bool $fail = false)

Return on error or display error message

Parameters

bool $fail

Should we return on errors, or stop

Return Value

null

at line 234
int sql_num_queries(bool $cached = false)

Return number of sql queries and cached sql queries used

Parameters

bool $cached

Should we return the number of cached or normal queries?

Return Value

int

Number of queries that have been executed

at line 242
null sql_add_num_queries(bool $cached = false)

Add to query count

Parameters

bool $cached

Is this query cached?

Return Value

null

at line 252
mixed sql_close()

DBAL garbage collection, close SQL connection

Return Value

mixed

False if no connection was opened before, Server response otherwise

at line 285
mixed sql_query_limit(string $query, int $total, int $offset = 0, int $cache_ttl = 0)

Build LIMIT query

Parameters

string $query

The SQL query to execute

int $total

The number of rows to select

int $offset
int $cache_ttl

Either 0 to avoid caching or the time in seconds which the result shall be kept in cache

Return Value

mixed

Buffered, seekable result handle, false on error

at line 302
mixed sql_fetchrowset(mixed $query_id = false)

Fetch all rows

Parameters

mixed $query_id

Already executed query to get the rows from, if false, the last query will be used.

Return Value

mixed

Nested array if the query had rows, false otherwise

at line 326
bool sql_rowseek(mixed $rownum, mixed $query_id)

Seek to given row number

Parameters

mixed $rownum

Row number the curser should point to Note: $rownum is 0 based

mixed $query_id

ID of the query to set the row cursor on if false, the last query will be used. $query_id will then be set correctly

Return Value

bool

False if something went wrong

at line 368
mixed sql_fetchfield(string $field, mixed $rownum = false, mixed $query_id = false)

Fetch field if rownum is false, the current row is used, else it is pointing to the row (zero-based)

Parameters

string $field

Name of the column

mixed $rownum

Row number, if false the current row will be used and the row curser will point to the next row Note: $rownum is 0 based

mixed $query_id

Already executed query to get the rows from, if false, the last query will be used.

Return Value

mixed

String value of the field in the selected row, false, if the row does not exist

at line 399
string sql_like_expression(string $expression)

Correctly adjust LIKE expression for special characters Some DBMS are handling them in a different way

Parameters

string $expression

The expression to use. Every wildcard is escaped, except $this->any_char and $this->one_char

Return Value

string

A SQL statement like: "LIKE 'bertie_%'"

at line 410
string sql_not_like_expression(string $expression)

Correctly adjust NOT LIKE expression for special characters Some DBMS are handling them in a different way

Parameters

string $expression

The expression to use. Every wildcard is escaped, except $this->any_char and $this->one_char

Return Value

string

A SQL statement like: "NOT LIKE 'bertie_%'"

at line 421
string sql_case(string $condition, string $action_true, mixed $action_false = false)

Build a case expression

Note: The two statements action_true and action_false must have the same data type (int, vchar, ...) in the database!

Parameters

string $condition

The condition which must be true, to use action_true rather then action_else

string $action_true

SQL expression that is used, if the condition is true

mixed $action_false

SQL expression that is used, if the condition is false

Return Value

string

CASE expression including the condition and statements

at line 433
string sql_concatenate(string $expr1, string $expr2)

Build a concatenated expression

Parameters

string $expr1

Base SQL expression where we append the second one

string $expr2

SQL expression that is appended to the first expression

Return Value

string

Concatenated string

at line 441
bool sql_buffer_nested_transactions()

Returns whether results of a query need to be buffered to run a transaction while iterating over them.

Return Value

bool

Whether buffering is required.

at line 449
mixed sql_transaction(string $status = 'begin')

SQL Transaction

Parameters

string $status

Should be one of the following strings: begin, commit, rollback

Return Value

mixed

Buffered, seekable result handle, false on error

at line 516
string sql_build_array(string $query, array $assoc_ary = false)

Build sql statement from an array

Parameters

string $query

Should be on of the following strings: INSERT, INSERT_SELECT, UPDATE, SELECT, DELETE

array $assoc_ary

Array with "column => value" pairs

Return Value

string

A SQL statement like "c1 = 'a' AND c2 = 'b'"

at line 564
string sql_in_set(string $field, array $array, bool $negate = false, bool $allow_empty_set = false)

Build IN or NOT IN sql comparison string, uses <> or = on single element arrays to improve comparison speed

Parameters

string $field

Name of the sql column that shall be compared

array $array

Array of values that are (not) allowed

bool $negate

true for NOT IN (), false for IN ()

bool $allow_empty_set

If true, allow $array to be empty, this function will return 1=1 or 1=0 then.

Return Value

string

A SQL statement like: "IN (1, 2, 3, 4)" or "= 1"

at line 606
string sql_bit_and(string $column_name, int $bit, string $compare = '')

Run binary AND operator on DB column.

Results in sql statement: "{$column_name} & (1 << {$bit}) {$compare}"

Parameters

string $column_name

The column name to use

int $bit

The value to use for the AND operator, will be converted to (1 << $bit). Is used by options, using the number schema: 0, 1, 2...29

string $compare

Any custom SQL code after the check (for example "= 0")

Return Value

string

A SQL statement like: "{$column} & (1 << {$bit}) {$compare}"

at line 619
string sql_bit_or(string $column_name, int $bit, string $compare = '')

Run binary OR operator on DB column.

Parameters

string $column_name

The column name to use

int $bit

The value to use for the OR operator, will be converted to (1 << $bit). Is used by options, using the number schema... 0, 1, 2...29

string $compare

Any custom SQL code after the check (e.g. "= 0")

Return Value

string

A SQL statement like "$column | (1 << $bit) {$compare}"

at line 632
string cast_expr_to_bigint(string $expression)

Returns SQL string to cast a string expression to an int.

Parameters

string $expression

An expression evaluating to string

Return Value

string

Expression returning an int

at line 640
string|false sql_nextid()

Gets the ID of the last inserted row immediately after an INSERT statement.

Note: Despite the name, the returned ID refers to the row that has just been inserted, rather than the hypothetical ID of the next row if a new one was to be inserted.

The returned value can be used for selecting the item that has just been inserted or for updating another table with an ID pointing to that item.

Alias of sql_last_inserted_id.

Return Value

string|false

Auto-incremented value of the last inserted row

at line 648
string cast_expr_to_string(string $expression)

Returns SQL string to cast an integer expression to a string.

Parameters

string $expression

An expression evaluating to int

Return Value

string

Expression returning a string

at line 656
string sql_lower_text(string $column_name)

Run LOWER() on DB column of type text (i.e. neither varchar nor char).

Parameters

string $column_name

The column name to use

Return Value

string

A SQL statement like "LOWER($column_name)"

at line 664
bool sql_multi_insert(string $table, array $sql_ary)

Run more than one insert statement.

Parameters

string $table

Table name to run the statements on

array $sql_ary

Multi-dimensional array holding the statement data

Return Value

bool

false if no statements were executed.

at line 736
string sql_build_query(string $query, array $array)

Build sql statement from array for select and select distinct statements

Possible query values: SELECT, SELECT_DISTINCT

Parameters

string $query

Should be one of: SELECT, SELECT_DISTINCT

array $array

Array with the query data: SELECT A comma imploded list of columns to select FROM Array with "table => alias" pairs, (alias can also be an array) Optional: LEFT_JOIN Array of join entries: FROM Table that should be joined ON Condition for the join Optional: WHERE Where SQL statement Optional: GROUP_BY Group by SQL statement Optional: ORDER_BY Order by SQL statement

Return Value

string

A SQL statement ready for execution

at line 848
protected _process_boolean_tree_first($operations_ary)

No description

Parameters

$operations_ary

at line 860
protected _process_boolean_tree($operations_ary)

No description

Parameters

$operations_ary

at line 975
mixed sql_error(string $sql = '')

Display sql error page

Parameters

string $sql

The SQL query causing the error

Return Value

mixed

Returns the full error message, if $this->return_on_error is set, null otherwise

at line 1045
mixed sql_report(string $mode, string $query = '')

Explain queries

Parameters

string $mode

Available modes: display, start, stop, add_select_row, fromcache, record_fromcache

string $query

The Query that should be explained

Return Value

mixed

Either a full HTML page, boolean or null

at line 1230
string get_estimated_row_count(string $table_name)

Gets the estimated number of rows in a specified table.

Parameters

string $table_name

Table name

Return Value

string

Number of rows in $table_name. Prefixed with ~ if estimated (otherwise exact).

at line 1238
string get_row_count(string $table_name)

Gets the exact number of rows in a specified table.

Parameters

string $table_name

Table name

Return Value

string

Exact number of rows in $table_name.

at line 1252
int|string clean_query_id(resource|int|string $query_id)

Ensure query ID can be used by cache

Parameters

resource|int|string $query_id

Mixed type query id

Return Value

int|string

Query id in string or integer format