class PDOConnector extends DBConnector implements TransactionManager (View source)

deprecated 4.13.0 Will be removed without equivalent functionality to replace it

PDO driver database connector

Traits

Provides extensions to this object to integrate it with standard config API methods.

Config options

write_operations array

List of operations to treat as write Implicitly includes all ddl_operations

from  DBConnector
ddl_operations array

List of operations to treat as DDL

from  DBConnector
emulate_prepare bool

Should ATTR_EMULATE_PREPARES flag be used to emulate prepared statements?

legacy_types bool

Should we return everything as a string in order to allow transaction savepoints? This preserves the behaviour of <= 4.3, including some bugs.

ssl_cipher_default string

Default strong SSL cipher to be used

Properties

protected PDO $pdoConnection

The PDO connection instance

protected string $databaseName

Name of the currently selected database

protected int|null $rowCount

If available, the row count of the last executed statement

protected array|null $lastStatementError

Error generated by the errorInfo() method of the last PDOStatement

protected array $cachedStatements

List of prepared statements, cached by SQL string

protected string $driver Driver
protected $inTransaction

Methods

public static 
config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

public
mixed
stat(string $name) deprecated

Get inherited config value

public
mixed
uninherited(string $name)

Gets the uninherited value for the given config option

public
$this
set_stat(string $name, mixed $value) deprecated

Update the config value for a given property

protected
databaseError(string $msg, int $errorLevel = E_USER_ERROR, string $sql = null, array $parameters = [])

Error handler for database errors.

public
bool
isQueryMutable(string $sql)

Determine if this SQL statement is a destructive operation (write or ddl)

public
bool
isQueryDDL(string $sql)

Determine if this SQL statement is a DDL operation

public
bool
isQueryWrite(string $sql)

Determine if this SQL statement is a write operation (alters content but not structure)

protected
bool
isQueryType(string $sql, string|array $type)

Determine if a query is of the given type

protected
array
parameterValues(array $parameters)

Extracts only the parameter values for error reporting

public
connect(array $parameters, bool $selectDB = false) deprecated

No description

public
string
getVersion()

Query for the version of the currently connected database

public
string
escapeString(string $value)

Given a value escape this for use in a query for the current database connector. Note that this does not quote the value.

public
string
quoteString(string $value)

Given a value escape and quote this appropriately for the current database connector.

public
query(string $sql, int $errorLevel = E_USER_ERROR)

Executes the following query with the specified error level.

public
preparedQuery(string $sql, array $parameters, int $errorLevel = E_USER_ERROR)

Execute the given SQL parameterised query with the specified arguments

public
bool
selectDatabase(string $name)

Select a database by name

public
string
getSelectedDatabase()

Retrieves the name of the currently selected database

public
unloadDatabase()

De-selects the currently selected database

public
string
getLastError()

Retrieves the last error generated from the database connection

public
int
getGeneratedID(string $table)

Determines the last ID generated from the specified table.

public
int
affectedRows()

Determines the number of affected rows from the last SQL query

public
bool
isActive()

Determines if we are connected to a server AND have a valid database selected.

public
__construct()

No description

public
flushStatements()

Flush all prepared statements

public
getOrPrepareStatement(string $sql)

Retrieve a prepared statement for a given SQL string, or return an already prepared version if one exists for the given query

public static 
bool
is_emulate_prepare()

Is PDO running in emulated mode

public
string
getDriver()

Return the driver for this connector E.g. 'mysql', 'sqlsrv', 'pgsql'

protected
beforeQuery(string $sql)

Invoked before any query is executed

public
int
exec(string $sql, int $errorLevel = E_USER_ERROR)

Executes a query that doesn't return a resultset

public
int
getPDOParamType(string $phpType)

Determines the PDO::PARAM_* type for a given PHP type string

public
bindParameters(PDOStatement $statement, array $parameters)

Bind all parameters to a PDOStatement

protected
prepareResults(PDOStatementHandle $statement, int $errorLevel, string $sql, array $parameters = [])

Given a PDOStatement that has just been executed, generate results and report any errors

protected
bool
hasError(PDOStatement|PDO $resource)

Determine if a resource has an attached error

public
bool
transactionStart(string|bool $transactionMode = false, string|bool $sessionCharacteristics = false)

Start a prepared transaction

public
bool
transactionEnd()

Complete a transaction

public
bool
transactionRollback(string $savepoint = null)

Roll-back a transaction

public
int
transactionDepth()

Return the depth of the transaction For unnested transactions returns 1 while in a transaction, 0 otherwise

public
transactionSavepoint(string $savepoint = null)

Create a new savepoint

public
bool
supportsSavepoints()

Return true if savepoints are supported by this transaction manager.

Details

static Config_ForClass config()

Get a configuration accessor for this class. Short hand for Config::inst()->get($this->class, .....).

Return Value

Config_ForClass

mixed stat(string $name) deprecated

deprecated 5.0 Use ->config()->get() instead

Get inherited config value

Parameters

string $name

Return Value

mixed

mixed uninherited(string $name)

Gets the uninherited value for the given config option

Parameters

string $name

Return Value

mixed

$this set_stat(string $name, mixed $value) deprecated

deprecated 5.0 Use ->config()->set() instead

Update the config value for a given property

Parameters

string $name
mixed $value

Return Value

$this

protected databaseError(string $msg, int $errorLevel = E_USER_ERROR, string $sql = null, array $parameters = [])

Error handler for database errors.

All database errors will call this function to report the error. It isn't a static function; it will be called on the object itself and as such can be overridden in a subclass. Subclasses should run all errors through this function.

hook this into a more well-structured error handling system.

Parameters

string $msg

The error message.

int $errorLevel

The level of the error to throw.

string $sql

The SQL related to this query

array $parameters

Parameters passed to the query

Exceptions

DatabaseException

bool isQueryMutable(string $sql)

Determine if this SQL statement is a destructive operation (write or ddl)

Parameters

string $sql

Return Value

bool

bool isQueryDDL(string $sql)

Determine if this SQL statement is a DDL operation

Parameters

string $sql

Return Value

bool

bool isQueryWrite(string $sql)

Determine if this SQL statement is a write operation (alters content but not structure)

Parameters

string $sql

Return Value

bool

protected bool isQueryType(string $sql, string|array $type)

Determine if a query is of the given type

Parameters

string $sql

Raw SQL

string|array $type

Type or list of types (first word in the query). Must be lowercase

Return Value

bool

protected array parameterValues(array $parameters)

Extracts only the parameter values for error reporting

Parameters

array $parameters

Return Value

array

List of parameter values

connect(array $parameters, bool $selectDB = false) deprecated

deprecated 4.5.0 Use native database drivers instead

No description

Parameters

array $parameters

List of parameters such as

  • type
  • server
  • username
  • password
  • database
  • path
bool $selectDB

By default database selection should be handled by the database controller (to enable database creation on the fly if necessary), but some interfaces require that the database is specified during connection (SQLite, Azure, etc).

string getVersion()

Query for the version of the currently connected database

Return Value

string

Version of this database

string escapeString(string $value)

Given a value escape this for use in a query for the current database connector. Note that this does not quote the value.

Parameters

string $value

The value to be escaped

Return Value

string

The appropritaely escaped string for value

string quoteString(string $value)

Given a value escape and quote this appropriately for the current database connector.

Parameters

string $value

The value to be injected into a query

Return Value

string

The appropriately escaped and quoted string for $value

query(string $sql, int $errorLevel = E_USER_ERROR)

Executes the following query with the specified error level.

Implementations of this function should respect previewWrite and benchmarkQuery

Parameters

string $sql

The SQL query to execute

int $errorLevel

For errors to this query, raise PHP errors using this error level.

Query preparedQuery(string $sql, array $parameters, int $errorLevel = E_USER_ERROR)

Execute the given SQL parameterised query with the specified arguments

Parameters

string $sql

The SQL query to execute. The ? character will denote parameters.

array $parameters

An ordered list of arguments.

int $errorLevel

The level of error reporting to enable for the query

Return Value

Query

bool selectDatabase(string $name)

Select a database by name

Parameters

string $name

Name of database

Return Value

bool

Flag indicating success

string getSelectedDatabase()

Retrieves the name of the currently selected database

Return Value

string

Name of the database, or null if none selected

unloadDatabase()

De-selects the currently selected database

string getLastError()

Retrieves the last error generated from the database connection

Return Value

string

The error message

int getGeneratedID(string $table)

Determines the last ID generated from the specified table.

Note that some connectors may not be able to return $table specific responses, and this parameter may be ignored.

Parameters

string $table

The target table to return the last generated ID for

Return Value

int

ID value

int affectedRows()

Determines the number of affected rows from the last SQL query

Return Value

int

Number of affected rows

bool isActive()

Determines if we are connected to a server AND have a valid database selected.

Return Value

bool

Flag indicating that a valid database is connected

__construct()

No description

flushStatements()

Flush all prepared statements

PDOStatementHandle|false getOrPrepareStatement(string $sql)

Retrieve a prepared statement for a given SQL string, or return an already prepared version if one exists for the given query

Parameters

string $sql

Return Value

PDOStatementHandle|false

static bool is_emulate_prepare()

Is PDO running in emulated mode

Return Value

bool

string getDriver()

Return the driver for this connector E.g. 'mysql', 'sqlsrv', 'pgsql'

Return Value

string

protected beforeQuery(string $sql)

Invoked before any query is executed

Parameters

string $sql

int exec(string $sql, int $errorLevel = E_USER_ERROR)

Executes a query that doesn't return a resultset

Parameters

string $sql

The SQL query to execute

int $errorLevel

For errors to this query, raise PHP errors using this error level.

Return Value

int

int getPDOParamType(string $phpType)

Determines the PDO::PARAM_* type for a given PHP type string

Parameters

string $phpType

Type of object in PHP

Return Value

int

PDO Parameter constant value

bindParameters(PDOStatement $statement, array $parameters)

Bind all parameters to a PDOStatement

Parameters

PDOStatement $statement
array $parameters

protected PDOQuery prepareResults(PDOStatementHandle $statement, int $errorLevel, string $sql, array $parameters = [])

Given a PDOStatement that has just been executed, generate results and report any errors

Parameters

PDOStatementHandle $statement
int $errorLevel
string $sql
array $parameters

Return Value

PDOQuery

protected bool hasError(PDOStatement|PDO $resource)

Determine if a resource has an attached error

Parameters

PDOStatement|PDO $resource

the resource to check

Return Value

bool

Flag indicating true if the resource has an error

bool transactionStart(string|bool $transactionMode = false, string|bool $sessionCharacteristics = false)

Start a prepared transaction

Parameters

string|bool $transactionMode

Transaction mode, or false to ignore. Deprecated and will be removed in SS5.

string|bool $sessionCharacteristics

Session characteristics, or false to ignore. Deprecated and will be removed in SS5.

Return Value

bool

True on success

Exceptions

DatabaseException

bool transactionEnd()

Complete a transaction

Return Value

bool

True on success

Exceptions

DatabaseException

bool transactionRollback(string $savepoint = null)

Roll-back a transaction

Parameters

string $savepoint

If set, roll-back to the named savepoint

Return Value

bool

True on success

Exceptions

DatabaseException

int transactionDepth()

Return the depth of the transaction For unnested transactions returns 1 while in a transaction, 0 otherwise

Return Value

int

transactionSavepoint(string $savepoint = null)

Create a new savepoint

Parameters

string $savepoint

The savepoint name

Exceptions

DatabaseException

bool supportsSavepoints()

Return true if savepoints are supported by this transaction manager.

Savepoints aren't supported by all database connectors (notably PDO doesn't support them) and should be used with caution.

Return Value

bool