PHP Class Basecoat\DB

Show file Open project: shutterstock/basecoat

Public Properties

Property	Type	Description
$bulkInsertSize	integer	Large inserts are broken up into multiple insert of this size
$debug	integer	Debugging turned on(1) or off(0)
$errorCntr	integer	Number of errors that have been generated
$errorCode	string	The last error code that was generated
$errorMsg	string	The last error message that was generated
$errors	array	List of errors that have been generated
$insertId	integer	Last insert ID
$instanceCntr	integer	Number of instances that have been created
$lastQuery	string	The last query that was run
$maxProfiling	integer	Maximum number of items to retain in profiling list
$selectResult	array	Default storage variable for select result if no variable is provided
$useErrorLog	integer	Also log errors via error_log

Public Methods

Method	Description
__construct ( mixed $host, string $username = null, string $password = null, string $db = null, $label = 'n/a' )	Initialize an instance of the database class.
__destruct ( )	Actions to perform when class is destructed
clearResult ( )	Clear $selectResult variable
connect ( $useMaster = false, $reconnect = false ) : mixed	Establish a connection to the database. Note: Connections are "on demand", you shouldn't need to call this function yourself Called automatically by execQuery if no connection.
delete ( $tablename, $filter, $filterBindings = null, boolean $useMaster = true, $modifiers = '' ) : integer	Delete records from the database
disconnect ( boolean $useMaster = false )	Disconnect from the database
execute ( $bindings = [], boolean $useMaster = false ) : integer	Execute a prepare statement to data binding values. Can be called repeatedly for the same prepared query, with different data bindings.
fetch ( boolean $useMaster = false, constant $method = null ) : array	Fetch one row of data from the database after SELECT query is run
fetchAll ( variable &$resultVar, string $keyField = null, boolean $grouped = false, boolean $useMaster = false, constant $method = null ) : integer	Fetch all rows from the database after SELECT query is run Rows can be fetched with a field as the index instead of sequential index By specifying a $keyField and $grouped, record will be returned grouped by the key field
fetchField ( string $fieldName, boolean $useMaster = false ) : array	Fetch a single field from a select query. Use for when you just want a list of values, like IDs, for processing.
foundRows ( boolean $useMaster = false ) : integer	Retrieve total rows found for last SELECT SQL_CALC_FOUND_ROWS query with LIMIT clause
getLastInsertId ( boolean $useMaster = true ) : integer	Get the last insert if for prepare/execute statements
getProfiling ( ) : array	Retrieve profiling information
getResult ( variable &$resultVar ) : array	Retrieve the contents of the $selectResult class variable and clear it
getServerInstance ( mixed $serverKey, boolean $new = false )	Return an instance of the class connected to the specified server If any instance of the request server already exist, that instance will be returned
insert ( string $tablename, array &$data, string $modifiers = '', boolean $useMaster = true, string $action = 'INSERT' ) : integer	Insert record(s) in database. The last insert ID is stored in the $insertId class variable
prepare ( string $query, boolean $useMaster = false, array $attr = null )	Prepare a query for execution by the execPrepared function
rawQuery ( string $query, boolean $useMaster = false ) : integer	Execute query. Can be called directly for complex query.
resetProfiling ( )	Resets the profiling array
select ( string $query, array $bindings = null, boolean $useMaster = false, boolean $fetchAll = false ) : integer	Run a SELECT query with optional data binding values
selectAll ( string $query, array $bindings = null, boolean $useMaster = false ) : mixed	Run a SELECT query with optional data binding values, and retrieves ALL rows This will use a separate statement handle so other outstanding queries do not get overwritten
selectOne ( string $query, array $bindings = null, boolean $useMaster = false ) : mixed	Run a SELECT query with optional data binding values, and retrieve only 1 row
setConnectParams ( mixed $host, string $username = null, string $password = null, string $db = null, string $label = 'n/a', array $attr = null )	Set database connection parameters. This does not establish a connection, only sets the parameters for a connection.
setConnectParamsMaster ( mixed $connectParams )	Set MASTER database connection parameters. This does not establish a connection, only sets the parameters for a connection.
setConnectTimeout ( integer $value, boolean $useMaster = false )	Set how long a db connection will be left open before disconnecting
setServerConfig ( array $servers, mixed $masterKey = null )	Set Server Connection Parameters The server list can have all the fields listed in $connectDefaults. At a minimum, it should have a lablel
update ( string $tablename, array $data, string $filter, string $filterBindings = null, boolean $useMaster = true ) : integer	Update record(s) in database

Private Methods

Method	Description
connectMaster ( $reconnect = false ) : mixed	Establish a connection to the Master server
explainQuery ( string $query, array $bindings = null, object &$dbh )	Run and EXPLAIN on a query for debugging puroposes.
logErrorInfo ( object $handle, $label = '' )	Log an error that occurred on a handle (database or statement)
updateProfiling ( string $query, array $bindings, float $qTime, string $result, string $label, mixed $debug = null )	Update profiling array with query information

Method Details

__construct() public method

Connections are not made at this time, only the parameters are set.

public __construct ( mixed $host, string $username = null, string $password = null, string $db = null, $label = 'n/a' )
$host	mixed	string (hostname) or associative array with parameter to use
$username	string	user name to use for login
$password	string	password to use for login
$db	string	optional database to select

__destruct() public method

Actions to perform when class is destructed

public __destruct ( )

clearResult() public method

Clear $selectResult variable

public clearResult ( )

connect() public method

Connection parameters must have already been set with setConnectParams Use $persistantConnections variable to toggle persistant connections (DON'T USE PERSISTANT CONNECTIONS UNLESS YOU KNOW WHY YOU SHOULDN'T)

public connect ( $useMaster = false, $reconnect = false ) : mixed
return	mixed	returns 1 on success or -1 on failure

delete() public method

Delete records from the database

public delete ( $tablename, $filter, $filterBindings = null, boolean $useMaster = true, $modifiers = '' ) : integer
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	number of rows deleted

disconnect() public method

Disconnect from the database

public disconnect ( boolean $useMaster = false )
$useMaster	boolean	disconnect from master/slave

execute() public method

Execute a prepare statement to data binding values. Can be called repeatedly for the same prepared query, with different data bindings.

public execute ( $bindings = [], boolean $useMaster = false ) : integer
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	returns number of rows that were affected, or -1 if query failed

fetch() public method

Fetch one row of data from the database after SELECT query is run

public fetch ( boolean $useMaster = false, constant $method = null ) : array
$useMaster	boolean	set to TRUE to use the master server connection
$method	constant	PDO method to use for fetch records (default is PDO::FETCH_ASSOC)
return	array	associative array of database record

fetchAll() public method

Fetch all rows from the database after SELECT query is run Rows can be fetched with a field as the index instead of sequential index By specifying a $keyField and $grouped, record will be returned grouped by the key field

public fetchAll ( variable &$resultVar, string $keyField = null, boolean $grouped = false, boolean $useMaster = false, constant $method = null ) : integer
$resultVar	variable	variable reference to store the result in
$keyField	string	field to use as the array key
$grouped	boolean	if $keyField specified, group by the key field
$useMaster	boolean	set to TRUE to use the master server connection
$method	constant	PDO method to use for fetch records (default is PDO::FETCH_ASSOC)
return	integer	1 if successful, -1 if error. Fetched data is stored in $selectResult class variable by default

fetchField() public method

Fetch a single field from a select query. Use for when you just want a list of values, like IDs, for processing.

public fetchField ( string $fieldName, boolean $useMaster = false ) : array
$fieldName	string	field name to get
$useMaster	boolean	set to TRUE to use the master server connection
return	array	list of values fetched

foundRows() public method

Retrieve total rows found for last SELECT SQL_CALC_FOUND_ROWS query with LIMIT clause

public foundRows ( boolean $useMaster = false ) : integer
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	number of total rows found

getLastInsertId() public method

Get the last insert if for prepare/execute statements

public getLastInsertId ( boolean $useMaster = true ) : integer
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	lsat insert id

getProfiling() public method

Retrieve profiling information

public getProfiling ( ) : array
return	array

getResult() public method

Retrieve the contents of the $selectResult class variable and clear it

public getResult ( variable &$resultVar ) : array
$resultVar	variable	variable reference to store the result in
return	array	contents of $selectResult variable

getServerInstance() public static method

Return an instance of the class connected to the specified server If any instance of the request server already exist, that instance will be returned

public static getServerInstance ( mixed $serverKey, boolean $new = false )
$serverKey	mixed	the $servers key to use for connecting
$new	boolean	force the creation of a new instance

insert() public method

Insert record(s) in database. The last insert ID is stored in the $insertId class variable

public insert ( string $tablename, array &$data, string $modifiers = '', boolean $useMaster = true, string $action = 'INSERT' ) : integer
$tablename	string	name of table to insert into
$data	array	associative array of field/value pairs to insert, can be multi-dimensional for bulk inserts. All fields must be the same for each record for bulk inserts
$modifiers	string	modifier to use in query (i.e. IGNORE). Default is no modifier
$useMaster	boolean	set to TRUE to use the master server connection
$action	string	type of insert to perform (INSERT, REPLACE). Default is INSERT
return	integer	number of rows that were inserted

prepare() public method

Prepare a query for execution by the execPrepared function

public prepare ( string $query, boolean $useMaster = false, array $attr = null )
$query	string	the query string, may contain data binding placeholder for use by execPrepared
$useMaster	boolean	set to TRUE to use the master server connection
$attr	array	custom PDO attributes to set $return int whether statement was successfully prepared (1), or not (-1)

rawQuery() public method

Used by various other functions (i.e. select, update, insert) to run a query/

public rawQuery ( string $query, boolean $useMaster = false ) : integer
$query	string	SQL query to run
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	result of running the query (not data)

resetProfiling() public method

Resets the profiling array

public resetProfiling ( )

select() public method

Run a SELECT query with optional data binding values

public select ( string $query, array $bindings = null, boolean $useMaster = false, boolean $fetchAll = false ) : integer
$query	string	SQL Select query to run
$bindings	array	array of values to bind to the query. Can be an associative array to bind by name
$useMaster	boolean	set to TRUE to use the master server connection
$fetchAll	boolean	1 to fetch data into an associated array ($this->selectResult), 0 to just run the query (use on of the fetch/fetchAll functions to retrieve data)
return	integer	returns number of rows selected. Use SQL_CALC_FOUND_ROWS with qFoundRows if using LIMIT, to get total rows found.

selectAll() public method

Run a SELECT query with optional data binding values, and retrieves ALL rows This will use a separate statement handle so other outstanding queries do not get overwritten

public selectAll ( string $query, array $bindings = null, boolean $useMaster = false ) : mixed
$query	string	SQL Select query to run
$bindings	array	array of values to bind to the query. Can be an associative array to bind by name
$useMaster	boolean	set to TRUE to use the master server connection
return	mixed	returns associative array of data on success, negative int on failure

selectOne() public method

Run a SELECT query with optional data binding values, and retrieve only 1 row

public selectOne ( string $query, array $bindings = null, boolean $useMaster = false ) : mixed
$query	string	SQL Select query to run
$bindings	array	array of values to bind to the query. Can be an associative array to bind by name
$useMaster	boolean	set to TRUE to use the master server connection
return	mixed	returns associative array of data on success, negative int on failure

setConnectParams() public method

Set database connection parameters. This does not establish a connection, only sets the parameters for a connection.

public setConnectParams ( mixed $host, string $username = null, string $password = null, string $db = null, string $label = 'n/a', array $attr = null )
$host	mixed	string (hostname) or associative array with parameter to use
$username	string	user name to use for login
$password	string	password to use for login
$db	string	optional database to select
$label	string	a "name" reference for the connection, used for profiling
$attr	array	connection attribute list (i.e. PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8")

setConnectParamsMaster() public static method

Set MASTER database connection parameters. This does not establish a connection, only sets the parameters for a connection.

public static setConnectParamsMaster ( mixed $connectParams )
$connectParams	mixed	associative array with parameters to use, see setConnectParams function

setConnectTimeout() public method

Set how long a db connection will be left open before disconnecting

public setConnectTimeout ( integer $value, boolean $useMaster = false )
$value	integer	seconds before timeout
$useMaster	boolean	set timeout value on master/slave connection

setServerConfig() public static method

Set Server Connection Parameters The server list can have all the fields listed in $connectDefaults. At a minimum, it should have a lablel

public static setServerConfig ( array $servers, mixed $masterKey = null )
$servers	array	list of servers to connect to. The array key should be the "id" of the server.
$masterKey	mixed	the array key in $servers that acts as the Master server

update() public method

Update record(s) in database

public update ( string $tablename, array $data, string $filter, string $filterBindings = null, boolean $useMaster = true ) : integer
$tablename	string	name of table to update
$data	array	associative array of field/value pairs to update. Note only raw data is supported, not formulas
$filter	string	SQL filter to apply to update, should be properly escaped
$filterBindings	string	associative array name/value pairs to use for binding. CAUTION: may override $data bindings if same names are used
$useMaster	boolean	set to TRUE to use the master server connection
return	integer	number of rows updated, or negative if an error occurred

Property Details

$bulkInsertSize public property

Large inserts are broken up into multiple insert of this size

public int $bulkInsertSize
return	integer

$debug public property

Debugging turned on(1) or off(0)

public int $debug
return	integer

$errorCntr public static property

Number of errors that have been generated

public static int $errorCntr
return	integer

$errorCode public property

The last error code that was generated

public string $errorCode
return	string

$errorMsg public property

The last error message that was generated

public string $errorMsg
return	string

$errors public static property

List of errors that have been generated

public static array $errors
return	array

$insertId public property

Last insert ID

public int $insertId
return	integer

$instanceCntr public static property

Number of instances that have been created

public static int $instanceCntr
return	integer

$lastQuery public property

The last query that was run

public string $lastQuery
return	string

$maxProfiling public static property

Maximum number of items to retain in profiling list

public static int $maxProfiling
return	integer

$selectResult public property

Default storage variable for select result if no variable is provided

public array $selectResult
return	array

$useErrorLog public property

Also log errors via error_log

public int $useErrorLog
return	integer