Documentation

DatabaseApiInterface
in

SMF

Interface DatabaseApiInterface

Methods

add_column() : bool: This function adds a column.
add_index() : bool: Add an index.
affected_rows() : int: Gets the number of rows affected by the last query.
allow_persistent() : bool: Figures out if persistent connection is allowed
backup_table() : resource|false: Backup $table to $backup_table.
calculate_type() : array<string|int, mixed>: Get the schema formatted name for a type.
change_column() : bool: Change a column. You only need to specify the column attributes that are changing.
connect_errno() : int: Gets the error code of last connection error.
connect_error() : string: Gets a description of the last connection error.
create_table() : bool: This function can be used to create a table without worrying about schema compatibilities across supported database systems.
create_word_search() : void: Highly specific function, to create the custom word index table.
cte_support() : bool: Function which return the information if the database supports cte with recursive
custom_order() : string: Function which constructs an optimize custom order string as an improved alternative to find_in_set()
data_seek() : bool: Adjusts the result pointer to an arbitrary row in a query result.
drop_table() : bool: Drop a table.
error() : string: Get the last error message string.
error_insert() : void: Save errors in the database safely.
escape_string() : string: Escapes special characters in a string for use in an SQL statement, taking into account the current character set of the connection.
escape_wildcard_string() : string: Escape the LIKE wildcards so that they match the character and not the wildcard.
fetch_all() : array<string|int, mixed>: Fetches all rows from a result as an array.
fetch_assoc() : array<string|int, mixed>: Fetch the next row of a result set as an associative array.
fetch_object() : object|false|null: Fetches all rows from a result as an object.
fetch_row() : array<string|int, mixed>|false: Fetch the next row of a result set as an enumerated array.
free_result() : bool: Frees the memory and data associated with the query result.
get_vendor() : string: Figures out if we are using MySQL, Percona or MariaDB
get_version() : string: Get the version number.
insert() : int|array<string|int, mixed>|null: Inserts one or more rows of data into a database table and optionally returns the resulting IDs.
insert_id() : int: Gets the ID of the most recently inserted row.
is_resource() : bool: Validates whether the resource is a valid mysqli instance.
list_columns() : array<string|int, mixed>: Return column information for a table.
list_indexes() : array<string|int, mixed>: Get index information.
list_tables() : array<string|int, mixed>: This function lists all tables in the database.
native_replace() : bool: Function which return the information if the database supports native replace inserts
num_fields() : int: Gets the number of fields in a result set.
num_rows() : int: Gets the number of rows in a result set.
optimize_table() : int: This function optimizes a table.
ping() : bool: Pings a server connection, and tries to reconnect if necessary.
query() : object|bool: Performs a query. Takes care of errors too.
quote() : string: Prepares a query string for execution, but does not perform the query.
remove_column() : bool: Removes a column.
remove_index() : bool: Remove an index.
search_language() : string|null: Return the language for the textsearch index
search_query() : resource: Returns the correct query for this search type.
search_support() : bool: This function will tell you whether this database type supports this search type.
select() : bool: Selects the default database for database queries.
server_info() : string: Gets information, such as the version, about the database server.
table_sql() : string: Dumps the schema (CREATE) for a table.
table_structure() : array<string|int, mixed>: Get table structure.
transaction() : bool: Do a transaction.
unescape_string() : string: Reverses the escape_string function.
update_from() : bool: Updates data in a table, using data from other tables.

add_column()

This function adds a column.


    public
                    add_column(string $table_name, array<string|int, mixed> $column_info[, array<string|int, mixed> $parameters = [] ][, string $if_exists = 'update' ][, string $error = 'fatal' ]) : bool

Parameters

$table_name : string: The name of the table to add the column to
$column_info : array<string|int, mixed>: An array of column info (smf_db_create_table)
$parameters : array<string|int, mixed> = []: Not used?
$if_exists : string = 'update': What to do if the column exists. If 'update', column is updated.
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

add_index()

Add an index.


    public
                    add_index(string $table_name, array<string|int, mixed> $index_info[, array<string|int, mixed> $parameters = [] ][, string $if_exists = 'update' ][, string $error = 'fatal' ]) : bool

Parameters

$table_name : string: The name of the table to add the index to
$index_info : array<string|int, mixed>: An array of index info (see )
$parameters : array<string|int, mixed> = []: Not used?
$if_exists : string = 'update': What to do if the index exists. If 'update', the definition will be updated.
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

affected_rows()

Gets the number of rows affected by the last query.


    public
                    affected_rows([object $connection = null ]) : int

Parameters

$connection : object = null: A connection to use (if null, $db_connection is used)

Return values

int —

The number of affected rows.

allow_persistent()

Figures out if persistent connection is allowed


    public
                    allow_persistent() : bool

Return values

bool

backup_table()

Backup $table to $backup_table.


    public
                    backup_table(string $table, string $backup_table) : resource|false

Parameters

$table : string: The name of the table to backup
$backup_table : string: The name of the backup table for this table

Return values

resource|false —

-the request handle to the table creation query, false if it failed.

calculate_type()

Get the schema formatted name for a type.


    public
                    calculate_type(string $type_name[, int $type_size = null ][, bool $reverse = false ]) : array<string|int, mixed>

Parameters

$type_name : string: The data type (int, varchar, smallint, etc.)
$type_size : int = null: The size (8, 255, etc.)
$reverse : bool = false

Return values

array<string|int, mixed> —

An array containing the appropriate type and size for this DB type

change_column()

Change a column. You only need to specify the column attributes that are changing.


    public
                    change_column(string $table_name, string $old_column, array<string|int, mixed> $column_info) : bool

Parameters

$table_name : string

The name of the table this column is in

$old_column : string

The name of the column we want to change

$column_info : array<string|int, mixed>

An array of info about the "new" column definition (see ) Note that $column_info also supports two additional parameters that only make sense when changing columns:

drop_default - to drop a default that was previously specified

Return values

bool

connect_errno()

Gets the error code of last connection error.


    public
                    connect_errno() : int

Return values

int —

Error code from the last connection attempt.

connect_error()

Gets a description of the last connection error.


    public
                    connect_error() : string

Return values

string —

Error message from the last connection attempt.

create_table()

This function can be used to create a table without worrying about schema compatibilities across supported database systems.


    public
                    create_table(string $table_name, array<string|int, mixed> $columns[, array<string|int, mixed> $indexes = [] ][, array<string|int, mixed> $parameters = [] ][, string $if_exists = 'ignore' ][, string $error = 'fatal' ]) : bool

If the table exists will, by default, do nothing.
Builds table with columns as passed to it - at least one column must be sent. The columns array should have one sub-array for each column - these sub arrays contain: 'name' = Column name 'type' = Type of column - values from (smallint, mediumint, int, text, varchar, char, tinytext, mediumtext, largetext) 'size' => Size of column (If applicable) - for example 255 for a large varchar, 10 for an int etc. If not set SMF will pick a size.
- 'default' = Default value - do not set if no default required.
- 'not_null' => Can it be null (true or false) - if not set default will be false.
- 'auto' => Set to true to make it an auto incrementing column. Set to a numerical value to set from what it should begin counting.
Adds indexes as specified within indexes parameter. Each index should be a member of $indexes. Values are:
- 'name' => Index name (If left empty SMF will generate).
- 'type' => Type of index. Choose from 'primary', 'unique' or 'index'. If not set will default to 'index'.
- 'columns' => Array containing columns that form part of key - in the order the index is to be created.
parameters: (None yet)
if_exists values:
- 'ignore' will do nothing if the table exists. (And will return true)
- 'overwrite' will drop any existing table of the same name.
- 'error' will return false if the table already exists.
- 'update' will update the table if the table already exists (no change of ai field and only columns with the same name keep the data)

Parameters

$table_name : string: The name of the table to create
$columns : array<string|int, mixed>: An array of column info in the specified format
$indexes : array<string|int, mixed> = []: An array of index info in the specified format
$parameters : array<string|int, mixed> = []: Extra parameters. Currently only 'engine', the desired MySQL storage engine, is used.
$if_exists : string = 'ignore': What to do if the table exists.
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

create_word_search()

Highly specific function, to create the custom word index table.


    public
                    create_word_search(string $size) : void

Parameters

$size : string: The column size type (int, mediumint (8), etc.). Not used here.

cte_support()

Function which return the information if the database supports cte with recursive


    public
                    cte_support() : bool

Return values

bool —

true or false

custom_order()

Function which constructs an optimize custom order string as an improved alternative to find_in_set()


    public
                    custom_order(string $field, array<string|int, mixed> $array_values[, bool $desc = false ]) : string

Parameters

$field : string: name
$array_values : array<string|int, mixed>: Field values sequenced in array via order priority. Must cast to int.
$desc : bool = false: default false

Return values

string —

case field when ... then ... end

data_seek()

Adjusts the result pointer to an arbitrary row in a query result.


    public
                    data_seek(object $result, int $offset) : bool

Parameters

$result : object
$offset : int: The row offset.

Return values

bool —

True on success, or false on failure.

drop_table()

Drop a table.


    public
                    drop_table(string $table_name[, array<string|int, mixed> $parameters = [] ][, string $error = 'fatal' ]) : bool

Parameters

$table_name : string: The name of the table to drop
$parameters : array<string|int, mixed> = []: Not used at the moment
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

error()

Get the last error message string.


    public
                    error(object $connection) : string

Parameters

$connection : object: The connection to use (if null, $db_connection is used)

Return values

string —

The last error message.

error_insert()

Save errors in the database safely.


    public
                    error_insert(array<string|int, mixed> $error_array) : void

$error_array must have the following keys in order: id_member, log_time, ip, url, message, session, error_type, file, line, backtrace

Parameters

$error_array : array<string|int, mixed>

escape_string()

Escapes special characters in a string for use in an SQL statement, taking into account the current character set of the connection.


    public
                    escape_string(string $string[, object $connection = null ]) : string

Parameters

$string : string
$connection : object = null: = null The connection to use (null to use $db_connection).

Return values

string —

The escaped string.

escape_wildcard_string()

Escape the LIKE wildcards so that they match the character and not the wildcard.


    public
                    escape_wildcard_string(string $string[, bool $translate_human_wildcards = false ]) : string

Parameters

$string : string: The string to escape
$translate_human_wildcards : bool = false: If true, turns human readable wildcards into SQL wildcards.

Return values

string —

The escaped string

fetch_all()

Fetches all rows from a result as an array.


    public
                    fetch_all(object $request) : array<string|int, mixed>

Parameters

$request : object: A query result resource.

Return values

array<string|int, mixed> —

An array that contains all rows (records) in the result resource.

fetch_assoc()

Fetch the next row of a result set as an associative array.


    public
                    fetch_assoc(object $result) : array<string|int, mixed>

Parameters

$result : object

Return values

array<string|int, mixed> —

One row of data, with string keys.

fetch_object()

Fetches all rows from a result as an object.


    public
                    fetch_object(object $result[, string $class = 'stdClass' ][, array<string|int, mixed> $args = [] ]) : object|false|null

Parameters

$result : object: A query result resource.
$class : string = 'stdClass': The name of the class to instantiate, set the properties of and return. If not specified, a stdClass object is returned.
$args : array<string|int, mixed> = []: An optional array of parameters to pass to the constructor for class objects.

Return values

object|false|null —

Returns an object representing the fetched row, where each property represents the name of the result set's column, null if there are no more rows in the result set, or false on failure.

fetch_row()

Fetch the next row of a result set as an enumerated array.


    public
                    fetch_row(object $result) : array<string|int, mixed>|false

Parameters

$result : object

Return values

array<string|int, mixed>|false —

One row of data, with numeric keys.

free_result()

Frees the memory and data associated with the query result.


    public
                    free_result(object $result) : bool

Parameters

$result : object

Return values

bool

get_vendor()

Figures out if we are using MySQL, Percona or MariaDB


    public
                    get_vendor() : string

Return values

string —

The database engine we are using

get_version()

Get the version number.


    public
                    get_version() : string

Return values

string —

The version

insert()

Inserts one or more rows of data into a database table and optionally returns the resulting IDs.


    public
                    insert(string $method, string $table, array<string|int, mixed> $columns, array<string|int, mixed> $data, array<string|int, mixed> $keys[, int $returnmode = 0 ][, object $connection = null ]) : int|array<string|int, mixed>|null

Parameters

$method : string: INSERT or REPLACE.
$table : string: The table (only used for Postgres).
$columns : array<string|int, mixed>: Array of the columns we're inserting the data into. Should contain 'column' => 'datatype' pairs.
$data : array<string|int, mixed>: Rows of data to insert. Each element of $data must be an array of values corresponding to $columns.
$keys : array<string|int, mixed>: The keys for the table. Must not empty in replace mode.
$returnmode : int = 0: 0 = nothing, 1 = last row ID, 2 = all row IDs. Default: 0.
$connection : object = null: The connection to use. If null, $db_connection is used.

Return values

int|array<string|int, mixed>|null —

Null if $returnmode is 0, the ID of the most recently inserted row if $returnmode is 1, or the IDS of all the inserted rows if $returnmode is 2.

insert_id()

Gets the ID of the most recently inserted row.


    public
                    insert_id(string $table[, string $field = null ][, object $connection = null ]) : int

Parameters

$table : string: The table (only used for Postgres)
$field : string = null: = null The specific field (not used here)
$connection : object = null: = null The connection (if null, $db_connection is used)

Return values

int —

The ID of the most recently inserted row

is_resource()

Validates whether the resource is a valid mysqli instance.


    public
                    is_resource(mixed $result) : bool

Mysqli uses objects rather than resource. https://bugs.php.net/bug.php?id=42797

Parameters

$result : mixed: The string to test

Return values

bool —

True if it is, false otherwise

list_columns()

Return column information for a table.


    public
                    list_columns(string $table_name[, bool $detail = false ][, array<string|int, mixed> $parameters = [] ]) : array<string|int, mixed>

Parameters

$table_name : string: The name of the table to get column info for
$detail : bool = false: Whether or not to return detailed info. If true, returns the column info. If false, just returns the column names.
$parameters : array<string|int, mixed> = []: Not used?

Return values

array<string|int, mixed> —

An array of column names or detailed column info, depending on $detail

list_indexes()

Get index information.


    public
                    list_indexes(string $table_name[, bool $detail = false ][, array<string|int, mixed> $parameters = [] ]) : array<string|int, mixed>

Parameters

$table_name : string: The name of the table to get indexes for
$detail : bool = false: Whether or not to return detailed info.
$parameters : array<string|int, mixed> = []: Not used?

Return values

array<string|int, mixed> —

An array of index names or a detailed array of index info, depending on $detail

list_tables()

This function lists all tables in the database.


    public
                    list_tables([string|bool $db = false ][, string|bool $filter = false ]) : array<string|int, mixed>

The listing could be filtered according to $filter.

Parameters

$db : string|bool = false: string The database name or false to use the current DB
$filter : string|bool = false: String to filter by or false to list all tables

Return values

array<string|int, mixed> —

An array of table names

native_replace()

Function which return the information if the database supports native replace inserts


    public
                    native_replace() : bool

Return values

bool —

true or false

num_fields()

Gets the number of fields in a result set.


    public
                    num_fields(object $result) : int

Parameters

$result : object

Return values

int —

The number of fields (columns) in the result.

num_rows()

Gets the number of rows in a result set.


    public
                    num_rows(object $result) : int

Parameters

$result : object

Return values

int —

The number of rows in the result.

optimize_table()

This function optimizes a table.


    public
                    optimize_table(string $table) : int

Parameters

$table : string: The table to be optimized

Return values

int —

How much space was gained

ping()

Pings a server connection, and tries to reconnect if necessary.


    public
                    ping([object $connection = null ]) : bool

Parameters

$connection : object = null: The connection object (if null, $db_connection is used)

Return values

bool —

True on success, or false on failure.

query()

Performs a query. Takes care of errors too.


    public
                    query(string $identifier, string $db_string[, array<string|int, mixed> $db_values = [] ][, object $connection = null ]) : object|bool

Parameters

$identifier : string: An identifier. Only used in PostgreSQL.
$db_string : string: The database string
$db_values : array<string|int, mixed> = []: = array() The values to be inserted into the string
$connection : object = null: = null The connection to use (null to use $db_connection)

Return values

object|bool —

Returns a query result resource (for SELECT queries), true (for UPDATE queries) or false if the query failed.

quote()

Prepares a query string for execution, but does not perform the query.


    public
                    quote(string $db_string, array<string|int, mixed> $db_values[, object $connection = null ]) : string

Parameters

$db_string : string: The database string.
$db_values : array<string|int, mixed>: An array of values to be injected into the string.
$connection : object = null: = null The connection to use (null to use $db_connection).

Return values

string —

The string with the values inserted.

remove_column()

Removes a column.


    public
                    remove_column(string $table_name, string $column_name[, array<string|int, mixed> $parameters = [] ][, string $error = 'fatal' ]) : bool

Parameters

$table_name : string: The name of the table to drop the column from
$column_name : string: The name of the column to drop
$parameters : array<string|int, mixed> = []: Not used?
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

remove_index()

Remove an index.


    public
                    remove_index(string $table_name, string $index_name[, array<string|int, mixed> $parameters = [] ][, string $error = 'fatal' ]) : bool

Parameters

$table_name : string: The name of the table to remove the index from
$index_name : string: The name of the index to remove
$parameters : array<string|int, mixed> = []: Not used?
$error : string = 'fatal'

Return values

bool —

Whether or not the operation was successful

search_language()

Return the language for the textsearch index


    public
                    search_language() : string|null

Return values

string|null —

The PostgreSQL search language, or null for MySQL.

search_query()

Returns the correct query for this search type.


    public
                    search_query(string $identifier, string $db_string[, array<string|int, mixed> $db_values = [] ][, object $connection = null ]) : resource

Parameters

$identifier : string: A query identifier
$db_string : string: The query text
$db_values : array<string|int, mixed> = []: An array of values to pass to $this->query()
$connection : object = null: The current DB connection resource

Return values

resource —

The query result resource from $this->query()

search_support()

This function will tell you whether this database type supports this search type.


    public
                    search_support(string $search_type) : bool

Parameters

$search_type : string: The search type.

Return values

bool —

Whether or not the specified search type is supported by this db system

select()

Selects the default database for database queries.


    public
                    select(string $database[, object $connection = null ]) : bool

Does nothing on PostgreSQL.

Parameters

$database : string: The database
$connection : object = null: The connection object (if null, $db_connection is used)

Return values

bool —

Whether the database was selected

server_info()

Gets information, such as the version, about the database server.


    public
                    server_info([object $connection = null ]) : string

Parameters

$connection : object = null: The connection to use (if null, $db_connection is used)

Return values

string —

The server info.

table_sql()

Dumps the schema (CREATE) for a table.


    public
                    table_sql(string $tableName) : string

Parameters

$tableName : string: The name of the table

Return values

string —

The "CREATE TABLE" SQL string for this table

table_structure()

Get table structure.


    public
                    table_structure(string $table_name) : array<string|int, mixed>

Parameters

$table_name : string: The name of the table

Return values

array<string|int, mixed> —

An array of table structure - the name, the column info from and the index info from

transaction()

Do a transaction.


    public
                    transaction([string $type = 'commit' ][, object $connection = null ]) : bool

Parameters

$type : string = 'commit': The step to perform (i.e. 'begin', 'commit', 'rollback')
$connection : object = null: The connection to use (if null, $db_connection is used)

Return values

bool —

True if successful, false otherwise

unescape_string()

Reverses the escape_string function.


    public
                    unescape_string(string $string) : string

Parameters

$string : string

Return values

string —

The unescaped string.

update_from()

Updates data in a table, using data from other tables.


    public
                    update_from(array<string|int, mixed> $table, array<string|int, mixed> $from_tables, string $set, string $where, array<string|int, mixed> $db_values[, object $connection = null ]) : bool

Parameters

$table : array<string|int, mixed>: Info about the table to be updated. Example: ['name' => '{db_prefix}foo', 'alias' => 'f']
$from_tables : array<string|int, mixed>: Info about the tables to get data from. Example: [ [ 'name' => '{db_prefix}bar', 'alias' => 'b', 'condition' => 'f.baz = b.qux', ] ]
$set : string: A string containing the SET instructions for the update query.
$where : string: A string containing any WHERE conditions for the update query.
$db_values : array<string|int, mixed>: The values to be inserted into the compiled query string.
$connection : object = null: The connection to use (if null, $db_connection will be used).

Return values

bool —

True if the update was successful, otherwise false.

DatabaseApiInterface in SMF

Table of Contents

Methods

Methods

add_column()

Parameters

Return values

add_index()

Parameters

Return values

affected_rows()

Parameters

Tags

Return values

allow_persistent()

Return values

backup_table()

Parameters

Return values

calculate_type()

Parameters

Return values

change_column()

Parameters

Return values

connect_errno()

Return values

connect_error()

Return values

create_table()

Parameters

Return values

create_word_search()

Parameters

cte_support()

Return values

custom_order()

Parameters

Return values

data_seek()

Parameters

Return values

drop_table()

Parameters

Return values

error()

Parameters

Return values

error_insert()

Parameters

escape_string()

Parameters

Return values

escape_wildcard_string()

Parameters

Return values

fetch_all()

Parameters

Return values

fetch_assoc()

Parameters

Return values

fetch_object()

Parameters

Return values

fetch_row()

Parameters

Return values

free_result()

Parameters

Return values

get_vendor()

Return values

get_version()

Return values

insert()

Parameters

Return values

insert_id()

Parameters

DatabaseApiInterface
in

SMF