PHP Class Habari\DatabaseConnection

Actual database connection.
Show file Open project: habari/system

Protected Properties

Property Type Description
$pdo PDO
$prefix an array of query profiles

Public Methods

Method Description
ConnectionFactory ( string $connect_string ) : mixed Returns the appropriate type of Connection class for the connect string passed or null on failure
add_error ( array $error ) Adds an error to the internal collection
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 ( string $connect_string, string $db_user, string $db_pass ) : boolean Connect to a database server
dbdelta ( $queries, $execute = true, $silent = true ) Automatic diffing function, used for determining required database upgrades.
delete ( string $table, array $keyfields ) : boolean Deletes any record that matches the specific criteria
disconnect ( ) : boolean Disconnect from the database server.
exec ( string $query ) : boolean Execute the given query on the database. Encapsulates PDO::exec.
execute_procedure ( string $procedure, array $args = [] ) : mixed Execute a stored procedure
exists ( string $table, array $keyfieldvalues ) : boolean Checks for a record that matches the specific criteria
filter_tables ( string $query ) : string Replace braced table names with their prefixed counterparts
get_column ( string $query, array $args = [] ) : array Returns all values for a column for a query
get_driver_name ( )
get_driver_version ( )
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 = [], 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 Execute a SQL statement.
query_file ( string $file ) : boolean Load a file containing queries, replace the prefix, execute all queries present
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
sql_t ( string $query, array &$args ) : string Translates the query for the current database engine
table ( string $name ) : string Get the full table name for the given table.
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, string $upgrade_path = '' ) : boolean Updates the content of the database between versions.
upgrade_post ( $old_version )
upgrade_pre ( $old_version )

Protected Methods

Method Description
load_tables ( ) : void Populate the table mapping.

Method Details

ConnectionFactory() public static method

Returns the appropriate type of Connection class for the connect string passed or null on failure
public static ConnectionFactory ( string $connect_string ) : mixed
$connect_string string a PDO connection string
return mixed returns appropriate DatabaseConnection child class instance or errors out if requiring the db class fails

add_error() public method

Adds an error to the internal collection
public add_error ( array $error )
$error array An array with error components

begin_transaction() public method

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

clear_errors() public method

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

commit() public method

Commit a currently running transaction
public commit ( )

connect() public method

Connect to a database server
public connect ( string $connect_string, string $db_user, string $db_pass ) : boolean
$connect_string string a PDO connection string
$db_user string the database user name
$db_pass string the database user password
return boolean true on success, false on error

dbdelta() public method

Implemented in child classes.
public dbdelta ( $queries, $execute = true, $silent = true )

delete() public method

Deletes any record that matches the specific criteria
public 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 method

Disconnect from the database server.
public disconnect ( ) : boolean
return boolean true

exec() public method

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

execute_procedure() public method

Execute a stored procedure
public 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 method

Checks for a record that matches the specific criteria
public 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' ) );

filter_tables() public method

Replace braced table names with their prefixed counterparts
public filter_tables ( string $query ) : string
$query string The query with {braced} table names
return string The translated query

get_column() public method

Returns all values for a column for a query
public 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 method

public get_driver_name ( )

get_driver_version() public method

public get_driver_version ( )

get_errors() public method

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

get_keyvalue() public method

Returns an associative array using the first returned column as the array key and the second as the array value
public 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= $dbconnection->get_keyvalue( 'SELECT keyfield, valuefield FROM tablename');

get_last_error() public method

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

get_profiles() public method

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

get_results() public method

Execute a query and return the results as an array of objects
public get_results ( string $query, array $args = [], string $class_name = '\Habari\QueryRecord' ) : array
$query string The query to execute
$args array An array of arguments to pass for prepared statements
$class_name string class name for row result objects
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 method

Returns a single row (the first in a multi-result set) object for a query
public 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 method

Return a single value from the database
public 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 method

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

in_transaction() public method

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

insert() public method

Inserts into the specified table values associated to the key fields
public 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' ) );

is_connected() public method

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

last_insert_id() public 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 last_insert_id ( ) : mixed
return mixed The last sequence value ( RDBMS-dependent! )

list_tables() public method

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

load_tables() protected method

Populate the table mapping.
protected load_tables ( ) : void
return void

query() public method

Execute a SQL statement.
public query ( string $query, array $args = [] ) : boolean
$query string the SQL statement
$args array values for the bound parameters
return boolean true on success, false on failure

query_file() public method

Load a file containing queries, replace the prefix, execute all queries present
public query_file ( string $file ) : boolean
$file string The filename containing the queries
return boolean True on successful execution of all queries

quote() public method

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

register_table() public 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 register_table ( string $name )
$name string the table name

rollback() public method

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

row_count() public method

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

set_fetch_class() public method

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

set_fetch_mode() public method

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

sql_t() public method

Translates the query for the current database engine
public sql_t ( string $query, array &$args ) : string
$query string The query to translate for the current database engine
$args array An array of SQL arguments
return string The translated query

table() public method

Get the full table name for the given table.
public table ( string $name ) : string
$name string name of the table
return string the full table name, or the original value if the table was not found

update() public method

function update Updates any record that matches the specific criteria A new row is inserted if no existing record matches the criteria
public 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 method

Implemented in child classes.
public upgrade ( integer $old_version, string $upgrade_path = '' ) : boolean
$old_version integer The old Version::DB_VERSION
$upgrade_path string
return boolean

upgrade_post() public method

public upgrade_post ( $old_version )

upgrade_pre() public method

public upgrade_pre ( $old_version )

Property Details

$pdo protected property

protected PDO $pdo
return PDO

$prefix protected property

an array of query profiles
protected $prefix