Documentation

DatabaseApiInterface
in

Interface DatabaseApiInterface

Table of Contents

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
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_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
Gets the ID of the most recently inserted row.
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.

Methods

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)

Tags
todo

PostgreSQL requires a $result param, not a $connection.

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
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 —

-the request handle to the table creation query

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 colums 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 failuer.

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_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()

Gets the ID of the most recently inserted row.

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
Parameters
$method : string

INSERT or REPLACE.

$table : string

The table (only used for Postgres).

$columns : array<string|int, mixed>

An array of the columns we're inserting the data into. Should contain 'column' => 'datatype' pairs.

$data : array<string|int, mixed>

The data to insert.

$keys : array<string|int, mixed>

The keys for the table, needs to be not empty on replace mode.

$returnmode : int = 0
$connection : object = null

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

Return values
int —

The ID of the most recently inserted row.

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

Tags
todo

why is this needed for?

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.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results