Composr API documentation
Back to top  

Database Driver.

package core_database_drivers

 Methods

Find whether the database may run GROUP BY unfettered with restrictions on the SELECT'd fields having to be represented in it or aggregate functions

can_arbitrary_groupby() : boolean

Returns

booleanWhether it can

Change the primary key of a table.

db_change_primary_key(\ID_TEXT $table_name, array $new_key, array $db) 

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

$db

array

The DB connection to make on

Close the database connections. We don't really need to close them (will close at exit), just disassociate so we can refresh them.

db_close_connections() 

Create a table index.

db_create_index(\ID_TEXT $table_name, \ID_TEXT $index_name, string $_fields, array $db) 

Parameters

$table_name

\ID_TEXT

The name of the table to create the index on

$index_name

\ID_TEXT

The index name (not really important at all)

$_fields

string

Part of the SQL query: a comma-separated list of fields to use on the index

$db

array

The DB connection to make on

Create a new table.

db_create_table(\ID_TEXT $table_name, array $fields, array $db, boolean $if_not_exists = false) 

Parameters

$table_name

\ID_TEXT

The table name

$fields

array

A map of field names to Composr field types (with *#? encodings)

$db

array

The DB connection to make on

$if_not_exists

boolean

Whether to only do it if it does not currently exist

Get the default password for making db connections (used by the installer as a default).

db_default_password() : string

Returns

stringThe default password for db connections

Get the default user for making db connections (used by the installer as a default).

db_default_user() : string

Returns

stringThe default user for db connections

Delete a table.

db_drop_table_if_exists(\ID_TEXT $table_name, array $db) 

Parameters

$table_name

\ID_TEXT

The table name

$db

array

The DB connection to delete on

This function is internal to the database system, allowing SQL statements to be build up appropriately. Some databases require IS NULL to be used to check for blank strings.

db_empty_is_null() : boolean

Returns

booleanWhether a blank string IS NULL

Encode a LIKE string comparision fragement for the database system. The pattern is a mixture of characters and ? and % wilcard symbols.

db_encode_like(string $pattern) : string

Parameters

$pattern

string

The pattern

Returns

stringThe encoded pattern

Escape a string so it may be inserted into a query. If SQL statements are being built up and passed using db_query then it is essential that this is used for security reasons. Otherwise, the abstraction layer deals with the situation.

db_escape_string(string $string) : string

Parameters

$string

string

The string

Returns

stringThe escaped string

Assemble part of a WHERE clause for doing full-text search

db_full_text_assemble(string $content, boolean $boolean) : string

Parameters

$content

string

Our match string (assumes "?" has been stripped already)

$boolean

boolean

Whether to do a boolean full text search

Returns

stringPart of a WHERE clause for doing full-text search

Get a database connection. This function shouldn't be used by you, as a connection to the database is established automatically.

db_get_connection(boolean $persistent, string $db_name, string $db_host, string $db_user, string $db_password, boolean $fail_ok = false) : \?array

Parameters

$persistent

boolean

Whether to create a persistent connection

$db_name

string

The database name

$db_host

string

The database host (the server)

$db_user

string

The database connection username

$db_password

string

The database connection password

$fail_ok

boolean

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

Returns

\?arrayA database connection (null: failed)

Get the ID of the first row in an auto-increment table (used whenever we need to reference the first).

db_get_first_id() : integer

Returns

integerFirst ID used

Get a map of Composr field types, to actual database types.

db_get_type_remap() : array

Returns

arrayThe map

Find whether full-text-search is present

db_has_full_text(array $db) : boolean

Parameters

$db

array

A DB connection

Returns

booleanWhether it is

Find whether full-text-boolean-search is present

db_has_full_text_boolean() : boolean

Returns

booleanWhether it is

Find whether subquery support is present

db_has_subqueries(array $db) : boolean

Parameters

$db

array

A DB connection

Returns

booleanWhether it is

Determine whether the database is a flat file database, and thus not have a meaningful connect username and password.

db_is_flat_file_simple() : boolean

Returns

booleanWhether the database is a flat file database

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

db_query(string $query, array $db, \?integer $max = null, \?integer $start = null, boolean $fail_ok = false, boolean $get_insert_id = false, boolean $no_syndicate = false, boolean $save_as_volatile = false) : \?mixed

Parameters

$query

string

The complete SQL query

$db

array

A DB connection

$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 not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$get_insert_id

boolean

Whether to get the autoincrement ID created for an insert query

$no_syndicate

boolean

Whether to force the query to execute on the XML database driver (won't optimise by using MySQL). Useful for calls happening for multi-part queries from within this DB driver

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension

Returns

\?mixedThe results (null: no results), or the insert ID

Encode an SQL statement fragment for a conditional to see if two strings are equal.

db_string_equal_to(\ID_TEXT $attribute, string $compare) : string

Parameters

$attribute

\ID_TEXT

The attribute

$compare

string

The comparison

Returns

stringThe SQL

Encode an SQL statement fragment for a conditional to see if two strings are not equal.

db_string_not_equal_to(\ID_TEXT $attribute, string $compare) : string

Parameters

$attribute

\ID_TEXT

The attribute

$compare

string

The comparison

Returns

stringThe SQL

See if an item is a prefix to something in the delimiter array.

is_start_of_delimiter(string $looking) : boolean

Parameters

$looking

string

The item

Returns

booleanWhether it is

Give out an error message and die, when a query fails.

_bad_query(string $query, boolean $fail_ok = false, \?string $error = null) : \?mixed

Parameters

$query

string

The query that failed

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$error

\?string

Error message (null: none)

Returns

\?mixedAlways returns null (null: error)

Write a record to an XML file.

_delete_record(\PATH $path, array $db) 

Parameters

$path

\PATH

The file path

$db

array

Database connection

Execute an ALTER query.

_do_query_alter(array $tokens, string $query, array $db, boolean $fail_ok) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?mixedThe results (null: no results)

Execute a CREATE query.

_do_query_create(array $tokens, string $query, array $db, boolean $fail_ok) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?mixedThe results (null: no results)

Execute a DELETE query.

_do_query_delete(array $tokens, string $query, array $db, \?integer $max, \?integer $start, boolean $fail_ok) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$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 not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?mixedThe results (null: no results)

Execute a DROP query.

_do_query_drop(array $tokens, string $query, array $db, boolean $fail_ok) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?mixedThe results (null: no results)

Wrapper to execute an INSERT query.

_do_query_insert(array $tokens, string $query, array $db, boolean $fail_ok, boolean $get_insert_id, \?integer $random_key, boolean $save_as_volatile = false) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$get_insert_id

boolean

Whether to get the autoincrement ID created for an insert query

$random_key

\?integer

The random key that we would use (null: not generated yet)

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension

Returns

\?mixedThe insert ID (null: not requested / error)

Execute an INSERT query.

_do_query_insert__execute(array $inserts, \ID_TEXT $table_name, string $query, array $db, boolean $fail_ok, boolean $get_insert_id, \?integer $random_key, boolean $save_as_volatile = false) : \?mixed

Parameters

$inserts

array

Rows being inserted

$table_name

\ID_TEXT

Table name we're inserting into

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$get_insert_id

boolean

Whether to get the autoincrement ID created for an insert query

$random_key

\?integer

The random key that we would use (null: not generated yet)

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension

Returns

\?mixedThe insert ID (null: not requested / error)

Parse an INSERT query.

_do_query_insert__parse(array $tokens, string $query, array $db, boolean $fail_ok) : \?array

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?arrayA pair: the table, and the rows to insert (null: error)

Execute a SELECT query.

_do_query_select(array $tokens, string $query, array $db, \?integer $max, \?integer $start, boolean $fail_ok, integer $at, boolean $do_end_check = true) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$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 not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$at

integer

Our offset counter

$do_end_check

boolean

Whether to not do the check to make sure we've parsed everything

Returns

\?mixedThe results (null: no results)

Execute an UPDATE query.

_do_query_update(array $tokens, string $query, array $db, \?integer $max, \?integer $start, boolean $fail_ok) : \?mixed

Parameters

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$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 not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?mixedThe results (null: no results)

Escape a value for use in a filesystem path.

_escape_name(string $in) : string

Parameters

$in

string

Value to escape (original value)

Returns

stringEscaped value

Execute an expression.

_execute_expression(array $expr, array $bindings, string $query) : \?mixed

Parameters

$expr

array

The expression

$bindings

array

Bindings available in the execution scope

$query

string

Query that was executed

Returns

\?mixedThe result (null: error/NULL)

Get results from a JOIN.

_execute_join(array $db, string $joined_as_prior, array $join, string $query, array $records, array $schema, array $where_expr, boolean $fail_ok = false) : \?array

Parameters

$db

array

Database connection

$joined_as_prior

string

The renaming of our table, so we can recognise it in the join condition

$join

array

Join op-tree

$query

string

Query that was executed

$records

array

Records so far

$schema

array

Schema so far

$where_expr

array

Expression filtering results (used for optimisation, seeing if we can get a quick key match)

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?arrayA pair: an array of results, an array of the schema for what has been joined (null: error)

Run SQL data filter functions over a result set.

_function_set_scoping(array $set, array $select, array $rep, string $query) : array

Parameters

$set

array

The set of results we are operating on

$select

array

Parse tree of what we are selecting

$rep

array

Record we are copying the function results into

$query

string

Query that was executed

Returns

arrayThe result row based on the set

Generate a GUID for a record, preferably from the key, but doesn't have to be.

_guid(\?array $schema = null, \?array $record = null) : string

Parameters

$schema

\?array

The schema (null: don't have/use)

$record

\?array

The record (null: don't have/use)

Returns

stringThe GUID

Check to see if there is a key conflict problem.

_key_conflict_check(array $db, string $table_name, array $schema, array $record, string $query, boolean $fail_ok, \?string $existing_identity = null) : boolean

Parameters

$db

array

Database connection

$table_name

string

The table name

$schema

array

The schema

$record

array

The record

$query

string

Query that was executed

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$existing_identity

\?string

The GUID representing what we have now (so we don't think we're conflicting with ourself) (null: not yet added)

Returns

booleanWhether there was a conflict

Check we've consumed all our tokens.

_parsing_check_ended(integer $at, array $tokens, string $query, boolean $fail_ok = false) : boolean

Parameters

$at

integer

Our offset counter

$tokens

array

Tokens

$query

string

Query that was executed

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

booleanSuccess status

Expect a certain token next.

_parsing_expects(integer $at, array $tokens, string $token, string $query, boolean $fail_ok = false) : boolean

Parameters

$at

integer

Our offset counter

$tokens

array

Tokens

$token

string

Token expected

$query

string

Query that was executed

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

booleanSuccess status

Reads the next token.

_parsing_read(integer $at, array $tokens, string $query, boolean $fail_ok = false) : \?string

Parameters

$at

integer

Our offset counter

$tokens

array

Tokens

$query

string

Query that was executed

$fail_ok

boolean

Whether it can return NULL if we're out of output (otherwise fails)

Returns

\?stringToken read (null: error, read too far)

Parse an SQL expression.

_parsing_read_expression(integer $at, array $tokens, string $query, array $db, boolean $look_for_connectives = true, boolean $look_for_any_connectives = true, boolean $fail_ok = false) : \?array

Parameters

$at

integer

Our offset counter

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$look_for_connectives

boolean

Whether to work as a connection point to seek out logic connection expression parts

$look_for_any_connectives

boolean

Whether to work as a connection point to seek out arithmetic connection expression parts

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?arrayThe expression (null: error)

Read in all the records from a table.

_read_all_records(array $db, string $table_name, string $table_as, \?array $schema, \?array $where_expr, boolean $fail_ok, string $query, boolean $include_unused_fields = false) : \?array

Parameters

$db

array

Database connection

$table_name

string

The table name

$table_as

string

What the table will be renamed to (blank: N/A)

$schema

\?array

Schema to type-set against (null: do not do type-setting)

$where_expr

\?array

Expression filtering results (used for optimisation, seeing if we can get a quick key match) (null: no data to filter with)

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$query

string

Query that was executed

$include_unused_fields

boolean

Whether to include fields that are present in the actual records but not in our schema

Returns

\?arrayThe collected records (null: error)

Read in a table specifier clause for a WHERE query.

_read_join(integer $at, array $tokens, string $query, array $db, boolean $fail_ok, integer $closing_brackets_needed) : \?array

Parameters

$at

integer

Our offset counter

$tokens

array

Tokens

$query

string

Query that was executed

$db

array

Database connection

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$closing_brackets_needed

integer

How many closing brackets we expect

Returns

\?arrayJoin condition (null: no join here)

Read a record from an XML file.

_read_record(\PATH $path, \?array $schema = null, \?array $must_contain_strings = null, boolean $include_unused_fields = false) : \?array

Parameters

$path

\PATH

The file path

$schema

\?array

Schema to type-set against (null: do not do type-setting)

$must_contain_strings

\?array

Substrings to check it is in, used for performance (null: none)

$include_unused_fields

boolean

Whether to include fields that are present in the actual records but not in our schema

Returns

\?arrayThe record map (null: does not contain requested substrings)

Find the schema for a table.

_read_schema(array $db, string $table_name, boolean $fail_ok = false) : \?array

Parameters

$db

array

The database

$table_name

string

The table name

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

Returns

\?arrayThe schema map (null: not found)

Optimize a join condition into a join scope set, if possible.

_setify_join_condition_for_optimisation(array $join_condition, array $schema, array $records, string $joined_as) : array

Parameters

$join_condition

array

Join condition (parsed WHERE-style clause)

$schema

array

Schema so far

$records

array

Records so far

$joined_as

string

The renaming of our table, so we can recognise it in the join condition

Returns

arrayAltered join condition

Take an expression and do our best to collapse it into a fixed mapping of stuff we know we are going to AND.

_turn_where_expr_to_map(array $where_expr, string $table_as, \?array $schema = null, boolean $not_full_accuracy = false) : array

Parameters

$where_expr

array

The expression parse tree

$table_as

string

What the table will be renamed to (blank: N/A)

$schema

\?array

Schema to type-set against (null: do not do type-setting)

$not_full_accuracy

boolean

Whether to do a not-full-accurate search

Returns

arrayAND map

Type check some data destined to go into a table.

_type_check(array $schema, array $record, string $query) 

Parameters

$schema

array

The schema

$record

array

The data

$query

string

Query that was executed

Unescape a value from a filesystem path back to the original.

_unescape_name(string $in) : string

Parameters

$in

string

Escaped value

Returns

stringOriginal value

Write a record to an XML file.

_write_record(array $db, string $table_name, string $guid, array $record, boolean $fail_ok = false, boolean $save_as_volatile = false) 

Parameters

$db

array

Database connection

$table_name

string

The table name

$guid

string

The GUID

$record

array

The record map

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)

$save_as_volatile

boolean

Whether we are saving as a 'volatile' file extension

Write in all the records to a table.

_write_records(array $db, string $table_name, array $records, boolean $fail_ok = false) 

Parameters

$db

array

Database connection

$table_name

string

The table name

$records

array

The list of record maps

$fail_ok

boolean

Whether to not output an error on some kind of run-time failure (parse errors and clear programming errors are always fatal)