Documentation

Base
in package
implements Adapter

Tags
author

Mike Naberezny mike@maintainable.com

author

Derek DeVries derek@maintainable.com

author

Chuck Hagenbuch chuck@horde.org

category

Horde

copyright

2007 Maintainable Software, LLC

copyright

2008-2021 Horde LLC

license

http://www.horde.org/licenses/bsd

subpackage

Adapter

Interfaces, Classes, Traits and Enums

Adapter
For compatibility reasons, we need to extend the Horde_Db_Adapter interface.

Table of Contents

$active  : bool
Is connection active?
$cache  : Horde_Cache
Cache object.
$cachePrefix  : string
Cache prefix.
$config  : array<string|int, mixed>
Config options.
$connection  : mixed
DB connection.
$lastQuery  : string
The last query sent to the database.
$logger  : Horde_Log_Logger
Log object.
$logQueries  : bool
Log query flag
$rowCount  : int
Row count of last action.
$runtime  : int
Runtime of last query.
$schema  : Schema
Schema object.
$schemaClass  : string
Schema class to use.
$schemaMethods  : array<string|int, mixed>
List of schema methods.
$transactionStarted  : int
Has a transaction been started?
__call()  : mixed
Delegate calls to the schema object.
__construct()  : mixed
Constructor.
__destruct()  : mixed
Free any resources that are open.
__sleep()  : mixed
Serialize callback.
__wakeup()  : mixed
Unserialize callback.
adapterName()  : string
Returns the human-readable name of the adapter. Use mixed case - one can always use downcase if needed.
addLimitOffset()  : string
Appends LIMIT and OFFSET options to a SQL statement.
addLock()  : mixed
Appends a locking clause to an SQL statement.
cacheRead()  : string|false
Reads values from the cache handler.
cacheWrite()  : mixed
Writes values to the cache handler.
delete()  : int
Executes the delete statement and returns the number of rows affected.
disconnect()  : mixed
Disconnect from db.
emptyInsertStatement()  : string
TODO
getCache()  : Horde_Cache
getLastQuery()  : string
Get the last query run
getLogger()  : mixed
return Horde_Log_Logger
getOption()  : mixed
Returns an adaptor option set through the constructor.
insertBlob()  : int
Inserts a row including BLOBs into a table.
insertFixture()  : mixed
Inserts the given fixture into the table. Overridden in adapters that require something beyond a simple insert (eg. Oracle).
isActive()  : bool
Is the connection active?
prefetchPrimaryKey()  : bool
Should primary key values be selected from their corresponding sequence before the insert statement? If true, next_sequence_value is called before each insert to set the record's primary key.
quote()  : void
quoteColumnName()  : string
quoteTableName()  : string
rawConnection()  : resource
Provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.
reconnect()  : mixed
Reconnect to the db.
resetRuntime()  : int
Reset the timer
sanitizeLimit()  : mixed
TODO
selectAll()  : array<string|int, mixed>
Returns an array of record hashes with the column names as keys and column values as values.
selectAssoc()  : array<string|int, mixed>
Returns an array where the keys are the first column of a select, and the values are the second column:
selectOne()  : array<string|int, mixed>
Returns a record hash with the column names as keys and column values as values.
selectValue()  : string
Returns a single value from a record
selectValues()  : array<string|int, mixed>
Returns an array of the values of the first column in a select: selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]
setCache()  : mixed
Set a cache object.
setLogger()  : mixed
Set a logger object.
supportsCountDistinct()  : bool
Does this adapter support using DISTINCT within COUNT? This is +true+ for all adapters except sqlite.
supportsInterval()  : bool
Does this adapter support using INTERVAL statements? This is +true+ for all adapters except sqlite.
supportsMigrations()  : bool
Does this adapter support migrations? Backend specific, as the abstract adapter always returns +false+.
transactionStarted()  : bool
Check if a transaction has been started.
update()  : int
Executes the update statement and returns the number of rows affected.
updateBlob()  : mixed
Updates rows including BLOBs into a table.
cacheKey()  : string
Returns the prefixed cache key to use.
checkRequiredConfig()  : mixed
Checks if required configuration keys are present.
formatLogEntry()  : string
Formats the log entry.
logError()  : mixed
logInfo()  : mixed
Logs the SQL query for debugging.
replaceParameters()  : string
Replace ? in a SQL statement with quoted values from $args

Properties

$active

Is connection active?

protected bool $active = null

$cache

Cache object.

protected Horde_Cache $cache

$cachePrefix

Cache prefix.

protected string $cachePrefix

$config

Config options.

protected array<string|int, mixed> $config = []

$connection

DB connection.

protected mixed $connection = null

$lastQuery

The last query sent to the database.

protected string $lastQuery

$logger

Log object.

protected Horde_Log_Logger $logger

$logQueries

Log query flag

protected bool $logQueries = false

$rowCount

Row count of last action.

protected int $rowCount = null

$runtime

Runtime of last query.

protected int $runtime

$schema

Schema object.

protected Schema $schema = null

$schemaClass

Schema class to use.

protected string $schemaClass = null

$schemaMethods

List of schema methods.

protected array<string|int, mixed> $schemaMethods = []

$transactionStarted

Has a transaction been started?

protected int $transactionStarted = 0

Methods

__call()

Delegate calls to the schema object.

public __call(string $method, array<string|int, mixed> $args) : mixed
Parameters
$method : string
$args : array<string|int, mixed>
Tags
throws
BadMethodCallException
Return values
mixed —

TODO

__construct()

Constructor.

public __construct(array<string|int, mixed> $config) : mixed
Parameters
$config : array<string|int, mixed>

Configuration options and optional objects:

'charset' - (string) TODO
Return values
mixed —

__destruct()

Free any resources that are open.

public __destruct() : mixed
Return values
mixed —

__sleep()

Serialize callback.

public __sleep() : mixed
Return values
mixed —

__wakeup()

Unserialize callback.

public __wakeup() : mixed
Return values
mixed —

adapterName()

Returns the human-readable name of the adapter. Use mixed case - one can always use downcase if needed.

public adapterName() : string
Return values
string —

addLimitOffset()

Appends LIMIT and OFFSET options to a SQL statement.

public addLimitOffset(string $sql, array<string|int, mixed> $options) : string
Parameters
$sql : string

SQL statement.

$options : array<string|int, mixed>

Hash with 'limit' and (optional) 'offset' values.

Return values
string —

addLock()

Appends a locking clause to an SQL statement.

public addLock(string &$sql[, array<string|int, mixed> $options = [] ]) : mixed

This method modifies the +sql+ parameter.

TODO: BC BREAK Rather return the modified string

SELECT * FROM suppliers FOR UPDATE

add_lock! 'SELECT * FROM suppliers', :lock => true add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'

Parameters
$sql : string

SQL statment.

$options : array<string|int, mixed> = []

TODO.

Return values
mixed —

cacheRead()

Reads values from the cache handler.

public cacheRead(string $key) : string|false

The key is automatically prefixed to avoid collisions when using different adapters or different configurations.

Parameters
$key : string

A cache key.

Tags
since

Horde_Db 2.1.0

Return values
string|false —

A value.

cacheWrite()

Writes values to the cache handler.

public cacheWrite(string $key, string $value) : mixed

The key is automatically prefixed to avoid collisions when using different adapters or different configurations.

Parameters
$key : string

A cache key.

$value : string

A value.

Tags
since

Horde_Db 2.1.0

Return values
mixed —

delete()

Executes the delete statement and returns the number of rows affected.

public delete(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : int
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
int —

Number of rows affected.

disconnect()

Disconnect from db.

public disconnect() : mixed
Return values
mixed —

emptyInsertStatement()

TODO

public emptyInsertStatement(string $tableName) : string
Parameters
$tableName : string

TODO

Return values
string —

TODO

getCache()

public getCache() : Horde_Cache
Return values
Horde_Cache —

getLastQuery()

Get the last query run

public getLastQuery() : string
Return values
string —

getLogger()

return Horde_Log_Logger

public getLogger() : mixed
Return values
mixed —

getOption()

Returns an adaptor option set through the constructor.

public getOption(string $option) : mixed
Parameters
$option : string

The option to return.

Return values
mixed —

The option value or null if option doesn't exist or is not set.

insertBlob()

Inserts a row including BLOBs into a table.

public insertBlob(string $table, array<string|int, mixed> $fields[, string $pk = null ][, mixed $idValue = null ]) : int
Parameters
$table : string

The table name.

$fields : array<string|int, mixed>

A hash of column names and values. BLOB/CLOB columns must be provided as Horde_Db_Value objects.

$pk : string = null

The primary key column.

$idValue : mixed = null

The primary key value. This parameter is required if the primary key is inserted manually.

Tags
since

Horde_Db 2.1.0

throws
DbException
Return values
int —

Last inserted ID.

insertFixture()

Inserts the given fixture into the table. Overridden in adapters that require something beyond a simple insert (eg. Oracle).

public insertFixture(mixed $fixture, string $tableName) : mixed
Parameters
$fixture : mixed

TODO

$tableName : string

TODO

Return values
mixed —

isActive()

Is the connection active?

public isActive() : bool
Return values
bool —

prefetchPrimaryKey()

Should primary key values be selected from their corresponding sequence before the insert statement? If true, next_sequence_value is called before each insert to set the record's primary key.

public prefetchPrimaryKey([mixed $tableName = null ]) : bool

This is false for all adapters but Firebird.

Parameters
$tableName : mixed = null
Tags
deprecated
Return values
bool —

quote()

public quote(mixed $value, mixed $column) : void
Parameters
$value : mixed
$column : mixed
Return values
void —

quoteColumnName()

public quoteColumnName(string $name) : string
Parameters
$name : string
Return values
string —

quoteTableName()

public quoteTableName(string $name) : string
Parameters
$name : string
Return values
string —

rawConnection()

Provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.

public rawConnection() : resource
Return values
resource —

reconnect()

Reconnect to the db.

public reconnect() : mixed
Return values
mixed —

resetRuntime()

Reset the timer

public resetRuntime() : int
Return values
int —

sanitizeLimit()

TODO

public sanitizeLimit(mixed $limit) : mixed
Parameters
$limit : mixed
Return values
mixed —

selectAll()

Returns an array of record hashes with the column names as keys and column values as values.

public selectAll(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed> —

selectAssoc()

Returns an array where the keys are the first column of a select, and the values are the second column:

public selectAssoc(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>

selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler']

Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed> —

selectOne()

Returns a record hash with the column names as keys and column values as values.

public selectOne(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed> —

selectValue()

Returns a single value from a record

public selectValue(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : string
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
string —

selectValues()

Returns an array of the values of the first column in a select: selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]

public selectValues(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : array<string|int, mixed>
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
array<string|int, mixed> —

setCache()

Set a cache object.

public setCache(Horde_Cache $cache) : mixed
Parameters
$cache : Horde_Cache

The cache object.

Tags
inject
Return values
mixed —

setLogger()

Set a logger object.

public setLogger(Horde_Log_Logger $logger[, mixed $log_queries = false ]) : mixed
Parameters
$logger : Horde_Log_Logger
$log_queries : mixed = false
Tags
inject
Return values
mixed —

supportsCountDistinct()

Does this adapter support using DISTINCT within COUNT? This is +true+ for all adapters except sqlite.

public supportsCountDistinct() : bool
Return values
bool —

supportsInterval()

Does this adapter support using INTERVAL statements? This is +true+ for all adapters except sqlite.

public supportsInterval() : bool
Return values
bool —

supportsMigrations()

Does this adapter support migrations? Backend specific, as the abstract adapter always returns +false+.

public supportsMigrations() : bool
Return values
bool —

transactionStarted()

Check if a transaction has been started.

public transactionStarted() : bool
Return values
bool —

True if transaction has been started.

update()

Executes the update statement and returns the number of rows affected.

public update(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : int
Parameters
$sql : string

SQL statement.

$arg1 : mixed = null

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

Tags
throws
DbException
Return values
int —

Number of rows affected.

updateBlob()

Updates rows including BLOBs into a table.

public updateBlob(string $table, array<string|int, mixed> $fields[, string|array<string|int, mixed> $where = null ]) : mixed
Parameters
$table : string

The table name.

$fields : array<string|int, mixed>

A hash of column names and values. BLOB/CLOB columns must be provided as Horde_Db_Value objects.

$where : string|array<string|int, mixed> = null

A WHERE clause. Either a complete clause or an array containing a clause with placeholders and a list of values.

Tags
since

Horde_Db 2.2.0

throws
DbException
Return values
mixed —

cacheKey()

Returns the prefixed cache key to use.

protected cacheKey(string $key) : string
Parameters
$key : string

A cache key.

Return values
string —

Prefixed cache key.

checkRequiredConfig()

Checks if required configuration keys are present.

protected checkRequiredConfig(array<string|int, mixed> $required) : mixed
Parameters
$required : array<string|int, mixed>

Required configuration keys.

Tags
throws
DbException

if a required key is missing.

Return values
mixed —

formatLogEntry()

Formats the log entry.

protected formatLogEntry(string $message, string $sql) : string
Parameters
$message : string

Message.

$sql : string

SQL statment.

Return values
string —

Formatted log entry.

logError()

protected logError(mixed $error, mixed $name[, mixed $runtime = null ]) : mixed
Parameters
$error : mixed
$name : mixed
$runtime : mixed = null
Return values
mixed —

logInfo()

Logs the SQL query for debugging.

protected logInfo(string $sql, array<string|int, mixed> $values[, string $name = null ][, float $runtime = null ]) : mixed
Parameters
$sql : string

SQL statement.

$values : array<string|int, mixed>

An array of values to substitute for placeholders.

$name : string = null

Optional queryname.

$runtime : float = null

Runtime interval.

Return values
mixed —

replaceParameters()

Replace ? in a SQL statement with quoted values from $args

protected replaceParameters(string $sql, array<string|int, mixed> $args[, bool $no_binary = false ]) : string
Parameters
$sql : string

SQL statement.

$args : array<string|int, mixed>

An array of values to bind.

$no_binary : bool = false

If true, do not replace any Horde_Db_Value_Binary values. Used for logging purposes.

Tags
throws
DbException
Return values
string —

Modified SQL statement.

Search results