Documentation

Oci8 extends Base
in package

Tags
author

Jan Schneider jan@horde.org

category

Horde

copyright

2013-2021 Horde LLC

license

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

since

Horde_Db 2.1.0

subpackage

Adapter

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.
beginDbTransaction()  : mixed
Begins the transaction (and turns off auto-committing).
cacheRead()  : string|false
Reads values from the cache handler.
cacheWrite()  : mixed
Writes values to the cache handler.
commitDbTransaction()  : mixed
Commits the transaction (and turns on auto-committing).
connect()  : mixed
Connect to the db
delete()  : int
Executes the delete statement and returns the number of rows affected.
disconnect()  : mixed
Disconnect from db
emptyInsertStatement()  : string
TODO
execute()  : resource
Executes the SQL statement in the context of this connection.
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.
insert()  : int
Inserts a row into a table.
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?
oracleCharsetName()  : string
Returns the Oracle name of a character set.
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
quoteString()  : string
Quotes a string, escaping any special characters.
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
rollbackDbTransaction()  : mixed
Rolls back the transaction (and turns on auto-committing). Must be done if the transaction block raises an exception or returns false.
sanitizeLimit()  : mixed
TODO
select()  : Result
Returns an array of records with the column names as keys, and column values as values.
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?
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.
errorMessage()  : string
Creates a formatted error message from a oci_error() result hash.
formatLogEntry()  : string
Formats the log entry.
handleError()  : mixed
Log and throws an exception for the last error.
logError()  : mixed
logInfo()  : mixed
Logs the SQL query for debugging.
prepareBlobs()  : array<string|int, mixed>
Prepares a list of field values to be consumed by insertBlob() or updateBlob().
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 = \Horde\Db\Adapter\Oracle\Schema::class

$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

beginDbTransaction()

Begins the transaction (and turns off auto-committing).

public beginDbTransaction() : mixed
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

commitDbTransaction()

Commits the transaction (and turns on auto-committing).

public commitDbTransaction() : mixed
Return values
mixed

connect()

Connect to the db

public connect() : mixed
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

execute()

Executes the SQL statement in the context of this connection.

public execute(string $sql[, mixed $arg1 = null ][, string $arg2 = null ][, mixed $lobs = [] ]) : resource
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.

$lobs : mixed = []
Tags
throws
DbException
Return values
resource

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.

insert()

Inserts a row into a table.

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

SQL statement.

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

Either an array of bound parameters or a query name.

$arg2 : string = null

If $arg1 contains bound parameters, the query name.

$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.

$sequenceName : string = null

The sequence name.

Tags
throws
DbException
Return values
int

Last inserted ID.

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

oracleCharsetName()

Returns the Oracle name of a character set.

public oracleCharsetName(string $charset) : string
Parameters
$charset : string

A charset name.

Return values
string

Oracle-normalized charset.

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

quoteString()

Quotes a string, escaping any special characters.

public quoteString(string $string) : string
Parameters
$string : 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

rollbackDbTransaction()

Rolls back the transaction (and turns on auto-committing). Must be done if the transaction block raises an exception or returns false.

public rollbackDbTransaction() : mixed
Return values
mixed

sanitizeLimit()

TODO

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

select()

Returns an array of records with the column names as keys, and column values as values.

public select(string $sql[, mixed $arg1 = null ][, string $arg2 = null ]) : Result
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
Result

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?

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

errorMessage()

Creates a formatted error message from a oci_error() result hash.

protected errorMessage(array<string|int, mixed> $error) : string
Parameters
$error : array<string|int, mixed>

Hash returned from oci_error().

Return values
string

The formatted error message.

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.

handleError()

Log and throws an exception for the last error.

protected handleError(resource $resource, string $method) : mixed
Parameters
$resource : resource

The resource (connection or statement) to call oci_error() upon.

$method : string

The calling method.

Tags
throws
DbException
Return values
mixed

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

prepareBlobs()

Prepares a list of field values to be consumed by insertBlob() or updateBlob().

protected prepareBlobs(array<string|int, mixed> $fields) : array<string|int, mixed>
Parameters
$fields : array<string|int, mixed>

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

Return values
array<string|int, mixed>

A list of fields, blobs, and locators.

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