PHP Class Habari\DB

Singleton class for database connection and manipulation
Inheritance: extends Singleton
Show file Open project: habari/system

Public Methods

Method Description
begin_transaction ( ) Start a transaction against the RDBMS in order to wrap multiple statements in a safe ACID-compliant container
clear_errors ( ) Updates the last error pointer to simulate resetting the error array
commit ( ) Commit a currently running transaction
connect ( ) : boolean Connects to the database server. If no arguments are supplied, then the connection is attempted for the database authentication variables in config.php.
dbdelta ( array $queries, boolean $execute = true, boolean $silent = true, boolean $doinserts = false ) : string Automatic database diffing function, used for determining required database upgrades.
delete ( string $table, array $keyfields ) : boolean Deletes any record that matches the specific criteria
disconnect ( )
exec ( string $query ) : boolean Execute the given query on the database. Encapsulates PDO::exec.
execute_procedure ( string $procedure, array $args = [] ) : mixed Executes a stored procedure against the database
exists ( string $table, array $keyfieldvalues ) : boolean Checks for a record that matches the specific criteria
get_column ( string $query, array $args = [] ) : array Returns all values for a column for a query
get_driver_name ( ) : mixed
get_driver_version ( ) : mixed
get_errors ( ) : array Returns error data gathered from database connection
get_keyvalue ( string $query, array $args = [] ) : array Returns an associative array using the first returned column as the array key and the second as the array value
get_last_error ( ) : array Returns only the last error info
get_profiles ( ) : array Returns query profiles
get_results ( string $query, array $args = [], null | string $class_name = '\Habari\QueryRecord' ) : array Execute a query and return the results as an array of objects
get_row ( string $query, array $args = [], string $class_name = '\Habari\QueryRecord' ) : object Returns a single row (the first in a multi-result set) object for a query
get_value ( string $query, array $args = [] ) : mixed Return a single value from the database
has_errors ( ) : boolean Determines if there have been errors since the last clear_errors() call
in_transaction ( ) : boolean Check whether there is a transaction underway.
insert ( string $table, array $fieldvalues ) : boolean Inserts into the specified table values associated to the key fields
is_connected ( ) : boolean Check whether there is an existing connection to a database.
last_insert_id ( ) : mixed Helper function to return the last inserted sequence or auto_increment field. Useful when doing multiple inserts within a single transaction -- for example, adding dependent related rows.
list_tables ( ) : array Returns a list of tables the DB currently knows about.
query ( string $query, array $args = [] ) : boolean Queries the database for a given SQL command.
quote ( string $string ) : string Return a PDO-quoted string appropriate for the DB backend we're using.
register_table ( string $name ) Adds a table to the list of tables known to Habari. Used by Theme and Plugin classes to inform the DB class about custom tables used by the plugin
rollback ( ) Rolls a currently running transaction back to the prexisting state, or, if the RDBMS supports it, whenever a savepoint was committed.
row_count ( ) : integer Returns number of rows affected by the last DELETE, INSERT, or UPDATE
set_fetch_class ( string $class_name ) Sets the class to fetch, if fetch mode is PDO::FETCH_CLASS
set_fetch_mode ( integer $mode ) Sets the fetch mode for return calls from PDOStatement
table ( string $name ) : string Helper function to naturally return table names
update ( string $table, array $fieldvalues, array $keyfields ) : boolean function update Updates any record that matches the specific criteria A new row is inserted if no existing record matches the criteria
upgrade ( integer $old_version ) : boolean Upgrade data in the database between database revisions
upgrade_post ( $old_version )
upgrade_pre ( $old_version )

Protected Methods

Method Description
instance ( ) : DB Enables singleton working properly

Private Methods

Method Description
add_error ( array $error ) Adds an error to the internal collection

Method Details

begin_transaction() public static method

Start a transaction against the RDBMS in order to wrap multiple statements in a safe ACID-compliant container
public static begin_transaction ( )

clear_errors() public static method

Updates the last error pointer to simulate resetting the error array
public static clear_errors ( )

commit() public static method

Commit a currently running transaction
public static commit ( )

connect() public static method

Connects to the database server. If no arguments are supplied, then the connection is attempted for the database authentication variables in config.php.
public static connect ( ) : boolean
return boolean

dbdelta() public static method

Automatic database diffing function, used for determining required database upgrades.
public static dbdelta ( array $queries, boolean $execute = true, boolean $silent = true, boolean $doinserts = false ) : string
$queries array array of create table and insert statements which constitute a fresh install
$execute boolean (optional) should the queries be executed against the database or just simulated. default = true
$silent boolean (optional) silent running with no messages printed? default = true
$doinserts boolean
return string translated SQL string

delete() public static method

Deletes any record that matches the specific criteria
public static delete ( string $table, array $keyfields ) : boolean
$table string Table to delete from
$keyfields array Associative array of field values to match
return boolean True on success, false if not DB::delete( 'mytable', array( 'fieldname' => 'value' ) );

disconnect() public static method

public static disconnect ( )

exec() public static method

WARNING: Make sure you don't call this with a SELECT statement. PDO will buffer the results and leave your cursor dangling.
public static exec ( string $query ) : boolean
$query string the query to run
return boolean true on success, false on error

execute_procedure() public static method

Executes a stored procedure against the database
public static execute_procedure ( string $procedure, array $args = [] ) : mixed
$procedure string Name of the stored procedure
$args array Arguments for the procedure
return mixed whatever the procedure returns...

exists() public static method

Checks for a record that matches the specific criteria
public static exists ( string $table, array $keyfieldvalues ) : boolean
$table string Table to check
$keyfieldvalues array Associative array of field values to match
return boolean True if any matching record exists, false if not DB::exists( 'mytable', array( 'fieldname' => 'value' ) );

get_column() public static method

Returns all values for a column for a query
public static get_column ( string $query, array $args = [] ) : array
$query string The query to execute
$args array Arguments to pass for prepared statements
return array An array containing the column data $ary = DB::get_column( 'SELECT col1 FROM tablename WHERE foo = ?', array('fieldvalue') );

get_driver_name() public static method

public static get_driver_name ( ) : mixed
return mixed

get_driver_version() public static method

public static get_driver_version ( ) : mixed
return mixed

get_errors() public static method

Returns error data gathered from database connection
public static get_errors ( ) : array
return array An array of error data

get_keyvalue() public static method

Returns an associative array using the first returned column as the array key and the second as the array value
public static get_keyvalue ( string $query, array $args = [] ) : array
$query string The query to execute
$args array Arguments to pass for prepared statements
return array An array containing the associative data $ary= DB::get_keyvalue( 'SELECT keyfield, valuefield FROM tablename');

get_last_error() public static method

Returns only the last error info
public static get_last_error ( ) : array
return array Data for the last error

get_profiles() public static method

Returns query profiles
public static get_profiles ( ) : array
return array an array of query profiles

get_results() public static method

Execute a query and return the results as an array of objects
public static get_results ( string $query, array $args = [], null | string $class_name = '\Habari\QueryRecord' ) : array
$query string the query to execute
$args array array of arguments to pass for prepared statements
$class_name null | string The name of the class name to return results as
return array An array of QueryRecord or the named class each containing the row data $ary = DB::get_results( 'SELECT * FROM tablename WHERE foo = ?', array('fieldvalue'), 'extendedQueryRecord' );

get_row() public static method

Returns a single row (the first in a multi-result set) object for a query
public static get_row ( string $query, array $args = [], string $class_name = '\Habari\QueryRecord' ) : object
$query string The query to execute
$args array Arguments to pass for prepared statements
$class_name string Optional class name for row result object
return object A QueryRecord or an instance of the named class containing the row data $obj = DB::get_row( 'SELECT * FROM tablename WHERE foo = ?', array('fieldvalue'), 'extendedQueryRecord' );

get_value() public static method

Return a single value from the database
public static get_value ( string $query, array $args = [] ) : mixed
$query string the query to execute
$args array Arguments to pass for prepared statements
return mixed a single value (int, string)

has_errors() public static method

Determines if there have been errors since the last clear_errors() call
public static has_errors ( ) : boolean
return boolean True if there were errors, false if not

in_transaction() public static method

Check whether there is a transaction underway.
public static in_transaction ( ) : boolean
return boolean

insert() public static method

Inserts into the specified table values associated to the key fields
public static insert ( string $table, array $fieldvalues ) : boolean
$table string The table name
$fieldvalues array An associative array of fields and values to insert
return boolean True on success, false if not DB::insert( 'mytable', array( 'fieldname' => 'value' ) );

instance() protected static method

Enables singleton working properly
protected static instance ( ) : DB
return DB

is_connected() public static method

Check whether there is an existing connection to a database.
public static is_connected ( ) : boolean
return boolean

last_insert_id() public static method

Helper function to return the last inserted sequence or auto_increment field. Useful when doing multiple inserts within a single transaction -- for example, adding dependent related rows.
See also: http://us2.php.net/manual/en/function.pdo-lastinsertid.php
public static last_insert_id ( ) : mixed
return mixed The last sequence value (RDBMS-dependent!)

list_tables() public static method

Returns a list of tables the DB currently knows about.
public static list_tables ( ) : array
return array The list of tables.

query() public static method

Queries the database for a given SQL command.
public static query ( string $query, array $args = [] ) : boolean
$query string the SQL query text
$args array array of values to use for placeholder replacement
return boolean

quote() public static method

If you're using this then there's 99+% probability you're building your queries the wrong way!
public static quote ( string $string ) : string
$string string The string to quote.
return string A DB-safe quoted string.

register_table() public static method

Adds a table to the list of tables known to Habari. Used by Theme and Plugin classes to inform the DB class about custom tables used by the plugin
public static register_table ( string $name )
$name string The table name

rollback() public static method

Rolls a currently running transaction back to the prexisting state, or, if the RDBMS supports it, whenever a savepoint was committed.
public static rollback ( )

row_count() public static method

Returns number of rows affected by the last DELETE, INSERT, or UPDATE
public static row_count ( ) : integer
return integer The number of rows affected.

set_fetch_class() public static method

Sets the class to fetch, if fetch mode is PDO::FETCH_CLASS
public static set_fetch_class ( string $class_name )
$class_name string Name of class to create during fetch

set_fetch_mode() public static method

Sets the fetch mode for return calls from PDOStatement
public static set_fetch_mode ( integer $mode )
$mode integer One of the PDO::FETCH_MODE integers

table() public static method

Helper function to naturally return table names
public static table ( string $name ) : string
$name string table name of the table
return string The name of the table

update() public static method

function update Updates any record that matches the specific criteria A new row is inserted if no existing record matches the criteria
public static update ( string $table, array $fieldvalues, array $keyfields ) : boolean
$table string Table to update
$fieldvalues array Associative array of field values to set
$keyfields array Associative array of field values to match
return boolean True on success, false if not DB::update( 'mytable', array( 'fieldname' => 'newvalue' ), array( 'fieldname' => 'value' ) );

upgrade() public static method

Upgrade data in the database between database revisions
public static upgrade ( integer $old_version ) : boolean
$old_version integer Optional version to upgrade to
return boolean

upgrade_post() public static method

public static upgrade_post ( $old_version )
$old_version

upgrade_pre() public static method

public static upgrade_pre ( $old_version )
$old_version