API Documentation

Methods

package	BackPress

Methods

PHP4 style constructor

BPDB() : \unknown

since	1.0

Returns

\unknownReturns the result of bpdb::__construct()

PHP5 style constructor

__construct() : void

Grabs the arguments, calls bpdb::_init() and then connects to the database

since	1.0

PHP5 style destructor, registered as shutdown function in PHP4

__destruct() : boolean

since	1.0

Returns

booleanAlways returns true

_escape()

_escape($data)

Parameters

$data

Initialises the class variables based on provided arguments

_init(array $args) : array

since	1.0

Parameters

$args

array

The provided connection settings

Returns

arrayThe current connection settings after processing by init

_real_escape()

_real_escape($string)

Parameters

$string

_weak_escape()

_weak_escape($string)

Parameters

$string

Wraps errors in a nice header and footer and dies.

bail(string $message) : false | void

Will not die if bpdb::$show_errors is true

since	1.0

Parameters

$message

string

Returns

falsevoid

Whether or not MySQL database is at least the required minimum version.

check_database_version($dbh_or_table = false) : \WP_Error

since	1.0

Parameters

$dbh_or_table

Returns

\WP_Error

Figure out which database server should handle the query, and connect to it.

db_connect(string $query = '') : resource

since	1.0

Parameters

$query

string

query

Returns

resourcemysql database connection

Connects to the database server and selects a database

db_connect_host(array $args) : void | boolean

since	1.0

Parameters

$args

array

args name => string DB name (required) user => string DB user (optional: false) password => string DB user password (optional: false) host => string DB hostname (optional: 'localhost') charset => string DB default charset. Used in a SET NAMES query. (optional) collate => string DB default collation. If charset supplied, optionally added to the SET NAMES query (optional)

Returns

voidbooleanvoid if cannot connect, false if cannot select, true if success

The database version number

db_version(false|string|resource $dbh_or_table = false) : false | string

since	1.0

Parameters

$dbh_or_table

falsestringresource

Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.

Returns

falsestringfalse on failure, version number on success

Escapes content for insertion into the database using addslashes(), for security

escape(string|array $data) : string

since	1.0

Parameters

$data

stringarray

Returns

stringquery safe string

Escapes content by reference for insertion into the database, for security

escape_by_ref($string)

since	1.0

Parameters

$string

Escapes array recursively for insertion into the database, for security

escape_deep(array $array)

Parameters

$array

array

Kill cached query results.

flush()

since	1.0

Retrieve the name of the function that called bpdb.

get_caller() : string

Requires PHP 4.3 and searches up the list of functions until it reaches the one that would most logically had called this method.

since	1.0

Returns

stringThe name of the calling function

Retrieve one column from the database.

get_col(string|null $query = null, integer $x = 0) : array

Executes a SQL query and returns the column from the SQL result. If the SQL result contains more than one column, this function returns the column specified. If $query is null, this function returns the specified column from the previous SQL result.

since	1.0

Parameters

$query

stringnull

SQL query. If null, use the result from the previous query.

$x

integer

Column to return. Indexed from 0.

Returns

arrayDatabase query result. Array indexed from 0 by SQL result row number.

Retrieve column metadata from the last query.

get_col_info(string $info_type = 'name', integer $col_offset = -1) : mixed

since	1.0

Parameters

$info_type

string

one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill

$col_offset

integer

0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type

Returns

mixedColumn Results

Get SQL/DB error

get_error(string $str = '')

since	1.0

Parameters

$str

string

Error string

Retrieve an entire SQL result set from the database (i.e., many rows)

get_results(string $query = null, string $output = OBJECT) : mixed

Executes a SQL query and returns the entire SQL result.

since	1.0

Parameters

$query

string

SQL query.

$output

string

(optional) ane of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K | ARRAY_K constants. With one of the first three, return an array of rows indexed from 0 by SQL result row number. Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively. With OBJECT_K and ARRAY_K, return an associative array of row objects keyed by the value of each row's first column's value. Duplicate keys are discarded.

Returns

mixedDatabase query results

Retrieve one row from the database.

get_row(string|null $query = null, string $output = OBJECT, integer $y = 0) : mixed

Executes a SQL query and returns the row from the SQL result.

since	1.0

Parameters

$query

stringnull

SQL query.

$output

string

(optional) one of ARRAY_A | ARRAY_N | OBJECT constants. Return an associative array (column => value, ...), a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively.

$y

integer

(optional) Row to return. Indexed from 0.

Returns

mixedDatabase query result in format specifed by $output

Retrieve one variable from the database.

get_var(string|null $query = null, integer $x = 0, integer $y = 0) : string

Executes a SQL query and returns the value from the SQL result. If the SQL result contains more than one column and/or more than one row, this function returns the value in the column and row specified. If $query is null, this function returns the value in the specified column and row from the previous SQL result.

since	1.0

Parameters

$query

stringnull

SQL query. If null, use the result from the previous query.

$x

integer

(optional) Column of value to return. Indexed from 0.

$y

integer

(optional) Row of value to return. Indexed from 0.

Returns

stringDatabase query result

Generic function to determine if a database supports a particular feature

has_cap(string $db_cap, false|string|resource $dbh_or_table = false) : boolean

since	1.0

Parameters

$db_cap

string

the feature

$dbh_or_table

falsestringresource

Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.

Returns

boolean

Disables showing of database errors.

hide_errors() : boolean

since	1.0

Returns

booleanWhether showing of errors was active or not

Insert a row into a table.

insert(string $table, array $data, array|string $format = null) : integer | false

wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )

since	1.0
see

Parameters

$table

string

table name

$data

array

Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).

$format

arraystring

(optional) An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data. A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $data will be treated as strings.

Returns

integerfalseThe number of rows inserted, or false on error.

Prepares a SQL query for safe execution. Uses sprintf()-like syntax.

prepare(string $query = null) : null | string

This function only supports a small subset of the sprintf syntax; it only supports %d (decimal number), %s (string). Does not support sign, padding, alignment, width or precision specifiers. Does not support argument numbering/swapping.

May be called like sprintf() or like vsprintf().

Both %d and %s should be left unquoted in the query string.

wpdb::prepare( "SELECT * FROM table WHERE column = %s AND field = %d", "foo", 1337 )

link	Description of syntax.
since	1.0

Parameters

$query

string

Query statement with sprintf()-like placeholders

Returns

nullstringSanitized query string

Print SQL/DB error.

print_error(string $str = '') : boolean

since	1.0

Parameters

$str

string

The error to display

Returns

booleanFalse if the showing of errors is disabled.

Perform a MySQL database query, using current database connection.

query(string $query, $use_current = false) : integer | false

More information can be found on the codex page.

since	1.0

Parameters

$query

string

$use_current

Returns

integerfalseNumber of rows affected/selected or false on error

Selects a database using the current database connection.

select(string $db, $dbh) : boolean

The database name will be changed based on the current database connection. On failure, the execution will bail and display an DB error.

since	1.0

Parameters

$db

string

MySQL database name

$dbh

Returns

booleanTrue on success, false on failure.

Sets the table prefix for the WordPress tables.

set_prefix(string $prefix, false | array $tables = false) : string

since	1.0

Parameters

$prefix

string

prefix

$tables

falsearray

tables (optional: false) table identifiers are array keys array values empty: set prefix: array( 'posts' => false, 'users' => false, ... ) string: set to that array value: array( 'posts' => 'my_posts', 'users' => 'my_users' ) OR array values (with numeric keys): array( 'posts', 'users', ... )

Returns

stringthe previous prefix (mostly only meaningful if all $table parameter was false)

Enables showing of database errors.

show_errors(boolean $show = true) : boolean

This function should be used only to enable showing of errors. bpdb::hide_errors() should be used instead for hiding of errors. However, this function can be used to enable and disable showing of database errors.

since	1.0

Parameters

$show

boolean

Whether to show or hide errors

Returns

booleanOld value for showing errors.

Whether of not the database supports collation.

supports_collation() : boolean

Called when BackPress is generating the table scheme.

since	1.0

Returns

booleanTrue if collation is supported, false if version does not

Whether to suppress database errors.

suppress_errors(boolean $suppress = true) : boolean

since	1.0

Parameters

$suppress

boolean

Returns

booleanprevious setting

Starts the timer, for debugging purposes.

timer_start() : true

since	1.0

Returns

true

Stops the debugging timer.

timer_stop() : integer

since	1.0

Returns

integerTotal time spent on the query, in milliseconds

Update a row in the table

update(string $table, array $data, array $where, array|string $format = null, $where_format = null) : integer | false

wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )

since	1.0
see

Parameters

$table

string

table name

$data

array

Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).

$where

array

A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".

$format

arraystring

(optional) An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data. A format is one of '%d', '%s' (decimal number, string). If omitted, all values in $data will be treated as strings.

$where_format

Returns

integerfalseThe number of rows updated, or false on error.

Properties

Saved info on the table column

$col_info : array

Default

array()

since	1.0
access	private

The currently connected MySQL connection resource.

$dbh : boolean | resource

Default

false

since	1.0
access	private

The last error during query.

$last_error : string

Default

''

since	1.0

The last query made

$last_query : string

Default

null

since	1.0
access	private

Amount of queries made

$num_queries : integer

Default

0

since	1.0
access	private

Table prefix

$prefix : string

Default

''

You can set this to have multiple installations in a single database. The second reason is for possible security precautions.

since	1.0
access	private

Saved queries that were executed

$queries : array

Default

array()

since	1.0
access	private

Whether the database queries are ready to start executing.

$ready : boolean

Default

false

since	1.0
access	private

Whether to use mysql_real_escape_string

$real_escape : boolean

Default

false

since	1.0
access	public

Whether to use the query log

$save_queries : boolean

Default

false

since	1.0
access	private

Whether to show SQL/DB errors

$show_errors : boolean

Default

false

since	1.0
access	private

Whether to suppress errors during the DB bootstrapping.

$suppress_errors : boolean

Default

false

access	private
since	1.0

List of tables

$tables : array

Default

array()

since	1.0
access	private