Database handling.

package core

 Methods

Construct a database driver from connection parameters.

__construct(string $db_name, string $db_host, string $db_user, string $db_password, string $table_prefix, boolean $fail_ok = false, \?object $static = null

Parameters

$db_name

string

The database name

$db_host

string

The database server

$db_user

string

The connection username

$db_password

string

The connection password

$table_prefix

string

The table prefix

$fail_ok

boolean

Whether to on error echo an error and return with a NULL, rather than giving a critical error

$static

\?object

Static call object (null: use global static call object)

This function is a very basic query executor. It shouldn't usually be used by you, as there are specialised abstracted versions available.

_query(string $query, \?integer $max = null, \?integer $start = null, boolean $fail_ok = false, boolean $get_insert_id = false, \?array $lang_fields = null, string $field_prefix = '', boolean $save_as_volatile = false) : \?mixed

Parameters

$query

string

The complete SQL query

$max

\?integer

The maximum number of rows to affect (null: no limit)

$start

\?integer

The start row to affect (null: no specification)

$fail_ok

boolean

Whether to output an error on failure

$get_insert_id

boolean

Whether to get an insert ID

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

$field_prefix

string

All the core fields have a prefix of this on them, so when we fiddle with language lookup we need to use this (only consider this if you're setting $lang_fields)

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension (used in the XML DB driver, to mark things as being non-syndicated to git)

Returns

\?mixedThe results (null: no result set) (empty array: empty result set)

Adds a field to an existing table.

add_table_field(\ID_TEXT $table_name, \ID_TEXT $name, \ID_TEXT $_type, \?mixed $default = null

Parameters

$table_name

\ID_TEXT

The table name

$name

\ID_TEXT

The field name

$_type

\ID_TEXT

The field type

$default

\?mixed

The default value (null: no default)

Change the type of a DB field in a table. Note: this function does not support ascession/decession of translatability

alter_table_field(\ID_TEXT $table_name, \ID_TEXT $name, \ID_TEXT $_type, \?ID_TEXT $new_name = null

Parameters

$table_name

\ID_TEXT

The table name

$name

\ID_TEXT

The field name

$_type

\ID_TEXT

The new field type

$new_name

\?ID_TEXT

The new field name (null: leave name)

Change the primary key of a table.

change_primary_key(\ID_TEXT $table_name, array $new_key) 

Parameters

$table_name

\ID_TEXT

The name of the table to create the index on

$new_key

array

A list of fields to put in the new key

Add an index to a table without disturbing the contents, after the table has been created.

create_index(\ID_TEXT $table_name, \ID_TEXT $index_name, array $fields, \ID_TEXT $unique_key_field = 'id'

Parameters

$table_name

\ID_TEXT

The table name

$index_name

\ID_TEXT

The index name

$fields

array

The fields

$unique_key_field

\ID_TEXT

The name of the unique key field for the table

Create a table with the given name and the given array of field name to type mappings.

create_table(\ID_TEXT $table_name, array $fields, boolean $skip_size_check = false, boolean $skip_null_check = false, boolean $save_bytes = false

If a field type starts '*', then it is part of that field's key. If it starts '?', then it is an optional field.

Parameters

$table_name

\ID_TEXT

The table name

$fields

array

The fields

$skip_size_check

boolean

Whether to skip the size check for the table (only do this for addon modules that don't need to support anything other than MySQL)

$skip_null_check

boolean

Whether to skip the check for NULL string fields

$save_bytes

boolean

Whether to use lower-byte table storage, with tradeoffs of not being able to support all unicode characters; use this if key length is an issue

Delete an index from a table.

delete_index_if_exists(\ID_TEXT $table_name, \ID_TEXT $index_name) 

Parameters

$table_name

\ID_TEXT

The table name

$index_name

\ID_TEXT

The index name

Delete the specified field from the specified table.

delete_table_field(\ID_TEXT $table_name, \ID_TEXT $name) 

Parameters

$table_name

\ID_TEXT

The table name

$name

\ID_TEXT

The field name

Drop the given table, or if it doesn't exist, silently return.

drop_table_if_exists(\ID_TEXT $table) 

Parameters

$table

\ID_TEXT

The table name

Get the table prefixes used for all Composr tables, commonly used when you are installing Composr in the same database as your forums. The default table prefix is 'cms4_'.

get_table_prefix() : string

Returns

stringThe table prefix

Initialise a filesystem DB that we can use for caching.

initialise_filesystem_db() 

If a text field has picked up Comcode support, we will need to run this.

promote_text_field_to_comcode(\ID_TEXT $table_name, \ID_TEXT $name, \ID_TEXT $key = 'id', integer $level = 2, boolean $in_assembly = false
set 1 2 3 4

Parameters

$table_name

\ID_TEXT

The table name

$name

\ID_TEXT

The field name

$key

\ID_TEXT

The tables key field name

$level

integer

The translation level to use

$in_assembly

boolean

Whether our data is already stored in Tempcode assembly format

This function is a raw query executor. It shouldn't usually be used unless you need to write SQL involving 'OR' statements or other complexities. There are abstracted versions available which you probably want instead (mainly, query_select).

query(string $query, \?integer $max = null, \?integer $start = null, boolean $fail_ok = false, boolean $skip_safety_check = false, \?array $lang_fields = null, string $field_prefix = '') : \?mixed

Parameters

$query

string

The complete SQL query

$max

\?integer

The maximum number of rows to affect (null: no limit)

$start

\?integer

The start row to affect (null: no specification)

$fail_ok

boolean

Whether to output an error on failure

$skip_safety_check

boolean

Whether to skip the query safety check

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

$field_prefix

string

All the core fields have a prefix of this on them, so when we fiddle with language lookup we need to use this (only consider this if you're setting $lang_fields)

Returns

\?mixedThe results (null: no result set) (empty array: empty result set)

Deletes rows from the specified table, that match the specified conditions (if any). It may be limited to a row range (it is likely, only a maximum, of 1, will be used, if any kind of range at all).

query_delete(string $table, \?array $where_map = null, string $end = '', \?integer $max = null, \?integer $start = null, boolean $fail_ok = false

Parameters

$table

string

The table name

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no conditions)

$end

string

Something to tack onto the end of the statement

$max

\?integer

The maximum number of rows to delete (null: no limit)

$start

\?integer

The starting row to delete (null: no specific start)

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

Insert a row.

query_insert(string $table, array $map, boolean $ret = false, boolean $fail_ok = false, boolean $save_as_volatile = false) : integer

Parameters

$table

string

The table name

$map

array

The insertion map

$ret

boolean

Whether to return the auto-insert-id

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension (used in the XML DB driver, to mark things as being non-syndicated to git)

Returns

integerThe ID of the new row

Do a named-parameter query, like "SELECT * FROM foo WHERE a='{value}';" with array('value' => 'b').

query_parameterised(string $query, array $parameters, \?integer $max = null, \?integer $start = null, boolean $fail_ok = false, boolean $skip_safety_check = false, \?array $lang_fields = null, string $field_prefix = '') : \?mixed

Assumes nothing looking like {example} is in the query already. Also supports {prefix} for encoding the table prefix. Lots of programmers like to do queries like this as it reduces the chance of accidentally forgetting to escape a parameter inserted directly/manually within a longer query. Usually in Composr we use APIs like query_select, which avoids the need for SQL all-together, but this doesn't work for all patterns of query.

Parameters

$query

string

The complete SQL query

$parameters

array

The query parameters (a map)

$max

\?integer

The maximum number of rows to affect (null: no limit)

$start

\?integer

The start row to affect (null: no specification)

$fail_ok

boolean

Whether to output an error on failure

$skip_safety_check

boolean

Whether to skip the query safety check

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

$field_prefix

string

All the core fields have a prefix of this on them, so when we fiddle with language lookup we need to use this (only consider this if you're setting $lang_fields)

Returns

\?mixedThe results (null: no result set) (empty array: empty result set)

Get the database rows found matching the specified parameters. Unlike 'query', it doesn't take raw SQL -- it assembles SQL based the parameters requested.

query_select(string $table, \?array $select = null, \?array $where_map = null, string $end = '', \?integer $max = null, \?integer $start = null, boolean $fail_ok = false, \?array $lang_fields = null) : array

Only use this if you're where condition is a series of AND clauses doing simple property comparisons.

Parameters

$table

string

The table name

$select

\?array

The SELECT map (null: all fields)

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no conditions)

$end

string

Something to tack onto the end of the SQL query

$max

\?integer

The maximum number of rows to select (null: get all)

$start

\?integer

The starting row to select (null: start at first)

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

Returns

arrayThe results (empty array: empty result set)

Get the specified value from the database. This is the specified value of the first row returned. A fatal error is produced if there is no matching row.

query_select_value(string $table, string $selected_value, \?array $where_map = null, string $end = '', boolean $fail_ok = false, \?array $lang_fields = null) : mixed

Parameters

$table

string

The table name

$selected_value

string

The field to select

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no where conditions)

$end

string

Something to tack onto the end

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

Returns

mixedThe first value of the first row returned

Get the specified value from the database, or NULL if there is no matching row (or if the value itself is NULL). This is good for detection existence of records, or for use if they might may or may not be present.

query_select_value_if_there(string $table, string $select, \?array $where_map = null, string $end = '', boolean $fail_ok = false, \?array $lang_fields = null) : \?mixed

Parameters

$table

string

The table name

$select

string

The field to select

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no where conditions)

$end

string

Something to tack onto the end

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

Returns

\?mixedThe first value of the first row returned (null: nothing found, or null value found)

Update (edit) a row in the database.

query_update(string $table, array $update_map, \?array $where_map = null, string $end = '', \?integer $max = null, \?integer $start = null, boolean $num_touched = false, boolean $fail_ok = false) : \?integer

Parameters

$table

string

The table name

$update_map

array

The UPDATE map

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no conditions)

$end

string

Something to tack onto the end of the statement

$max

\?integer

The maximum number of rows to update (null: no limit)

$start

\?integer

The starting row to update (null: no specific start)

$num_touched

boolean

Whether to get the number of touched rows. WARNING: Do not use in core Composr code as it does not work on all database drivers

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

Returns

\?integerThe number of touched records (null: hasn't been asked / error)

This function is a variant of query_select_value_if_there, by the fact that it only accepts a complete (and perfect) SQL query, instead of assembling one itself from the specified parameters.

query_value_if_there(string $query, boolean $fail_ok = false, boolean $skip_safety_check = false, \?array $lang_fields = null) : \?mixed

Parameters

$query

string

The complete SQL query

$fail_ok

boolean

Whether to allow failure (outputting a message instead of exiting completely)

$skip_safety_check

boolean

Whether to skip the query safety check

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

Returns

\?mixedThe first value of the first row returned (null: nothing found, or null value found)

If we've changed what $type is stored as, this function will need to be called to change the typing in the DB.

refresh_field_definition(\ID_TEXT $type) 

Parameters

$type

\ID_TEXT

The field type

Rename the given table.

rename_table(\ID_TEXT $old, \ID_TEXT $new) 

Parameters

$old

\ID_TEXT

The old table name

$new

\ID_TEXT

The new table name

Check if a table exists.

table_exists(\ID_TEXT $tablename) : boolean

Parameters

$tablename

\ID_TEXT

The table name

Returns

booleanWhether it exists

Find if a table is locked for more than 5 seconds. Only works with MySQL.

table_is_locked(\ID_TEXT $table) : boolean

Parameters

$table

\ID_TEXT

The table name

Returns

booleanWhether the table is locked

Convert a field name of type SHORT/LONG_TRANS[__COMCODE] into something we may use directly in our SQL.

translate_field_ref(\ID_TEXT $field_name) : \ID_TEXT

Assumes the query has separately been informed of the $lang_fields parameter (which is automatic for query_select).

Parameters

$field_name

\ID_TEXT

Language field name

Returns

\ID_TEXTSQL field name reference

Work out $lang_fields from analysing the table, if needed.

_automatic_lang_fields(string $table, string $full_table, array $select, \?array $where_map, string $end, \?array $lang_fields) 

Parameters

$table

string

The table name

$full_table

string

The table name, with prefix too

$select

array

The SELECT map

$where_map

\?array

The WHERE map [will all be AND'd together] (null: no conditions)

$end

string

Something to tack onto the end of the SQL query

$lang_fields

\?array

Extra language fields to join in for cache-prefilling. You only need to send this if you are doing a JOIN and carefully craft your query so table field names won't conflict (null: none)

Create a SELECT query from some abstract data.

_get_where_expand(string $table, \?array $select_map = null, \?array $where_map = null, string $end = '') : string

Parameters

$table

string

The table to select from

$select_map

\?array

List of field selections (null: all fields)

$where_map

\?array

Map of conditions to enforce (null: no conditions)

$end

string

Additional stuff to tack onto the query

Returns

stringSQL query

Extract the first of the first of the list of maps.

_query_select_value(array $values) : mixed

Parameters

$values

array

The list of maps

Returns

mixedThe first value of the first row in the list

 Properties

 

$connection_read

$connection_read 

Default

 

$connection_write

$connection_write 

Default

 

$dedupe_mode

$dedupe_mode 

Default

false
 

$static_ob

$static_ob 

Default

 

$table_exists_cache

$table_exists_cache 

Default

 

$table_prefix

$table_prefix 

Default

 

$text_lookup_cache

$text_lookup_cache 

Default

 

$text_lookup_original_cache

$text_lookup_original_cache 

Default