class Connection extends Connection (View source)

Portability wrapper for a Connection.

Constants

TRANSACTION_READ_UNCOMMITTED

Constant for transaction isolation level READ UNCOMMITTED.

TRANSACTION_READ_COMMITTED

Constant for transaction isolation level READ COMMITTED.

TRANSACTION_REPEATABLE_READ

Constant for transaction isolation level REPEATABLE READ.

TRANSACTION_SERIALIZABLE

Constant for transaction isolation level SERIALIZABLE.

PARAM_INT_ARRAY

Represents an array of ints to be expanded by Doctrine SQL parsing.

PARAM_STR_ARRAY

Represents an array of strings to be expanded by Doctrine SQL parsing.

ARRAY_PARAM_OFFSET

Offset by which PARAM_* constants are detected as arrays of the param type.

PORTABILITY_ALL

PORTABILITY_NONE

PORTABILITY_RTRIM

PORTABILITY_EMPTY_TO_NULL

PORTABILITY_FIX_CASE

PORTABILITY_DB2

PORTABILITY_ORACLE

PORTABILITY_POSTGRESQL

PORTABILITY_SQLITE

PORTABILITY_OTHERVENDORS

PORTABILITY_DRIZZLE

PORTABILITY_SQLANYWHERE

PORTABILITY_SQLSRV

Properties

protected Connection $_conn The wrapped driver connection. from Connection
protected Configuration $_config from Connection
protected EventManager $_eventManager from Connection
protected ExpressionBuilder $_expr from Connection
protected AbstractSchemaManager $_schemaManager The schema manager. from Connection
protected Driver $_driver The used DBAL driver. from Connection
protected integer $defaultFetchMode from Connection

Methods

__construct(array $params, Driver $driver, Configuration $config = null, EventManager $eventManager = null)

Initializes a new instance of the Connection class.

array
getParams()

Gets the parameters used during instantiation.

string
getDatabase()

Gets the name of the database this Connection is connected to.

string|null
getHost()

Gets the hostname of the currently connected database.

mixed
getPort()

Gets the port of the currently connected database.

string|null
getUsername()

Gets the username used by this connection.

string|null
getPassword()

Gets the password used by this connection.

getDriver()

Gets the DBAL driver instance.

getConfiguration()

Gets the Configuration used by the Connection.

EventManager
getEventManager()

Gets the EventManager used by the Connection.

getDatabasePlatform()

Gets the DatabasePlatform for the connection.

getExpressionBuilder()

Gets the ExpressionBuilder for the connection.

boolean
connect()

Establishes the connection with the database.

boolean
isAutoCommit()

Returns the current auto-commit mode for this connection.

setAutoCommit(boolean $autoCommit)

Sets auto-commit mode for this connection.

void
setFetchMode(integer $fetchMode)

Sets the fetch mode.

array
fetchAssoc(string $statement, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the first row of the result as an associative array.

array
fetchArray(string $statement, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the first row of the result as a numerically indexed array.

mixed
fetchColumn(string $statement, array $params = array(), integer $column = 0, array $types = array())

Prepares and executes an SQL query and returns the value of a single column of the first row of the result.

boolean
isConnected()

Whether an actual connection to the database is established.

boolean
isTransactionActive()

Checks whether a transaction is currently active.

integer
delete(string $tableExpression, array $identifier, array $types = array())

Executes an SQL DELETE statement on a table.

void
close()

Closes the connection.

integer
setTransactionIsolation(integer $level)

Sets the transaction isolation level.

integer
getTransactionIsolation()

Gets the currently active transaction isolation level.

integer
update(string $tableExpression, array $data, array $identifier, array $types = array())

Executes an SQL UPDATE statement on a table.

integer
insert(string $tableExpression, array $data, array $types = array())

Inserts a table row with specified data.

string
quoteIdentifier(string $str)

Quotes a string so it can be safely used as a table or column name, even if it is a reserved name.

string
quote(string $input, integer $type = null)

Quotes a given input parameter.

array
fetchAll(string $sql, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the result as an associative array.

prepare(string $statement)

Prepares an SQL statement.

executeQuery(string $query, array $params = array(), array $types = array(), QueryCacheProfile $qcp = null)

Executes an, optionally parametrized, SQL query.

executeCacheQuery(string $query, array $params, array $types, QueryCacheProfile $qcp)

Executes a caching query.

array
project(string $query, array $params, Closure $function)

Executes an, optionally parametrized, SQL query and returns the result, applying a given projection/transformation function on each row of the result.

query()

Executes an SQL statement, returning a result set as a Statement object.

integer
executeUpdate(string $query, array $params = array(), array $types = array())

Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.

integer
exec(string $statement)

Executes an SQL statement and return the number of affected rows.

integer
getTransactionNestingLevel()

Returns the current transaction nesting level.

string|null
errorCode()

Fetches the SQLSTATE associated with the last database operation.

array
errorInfo()

Fetches extended error information associated with the last database operation.

string
lastInsertId(string|null $seqName = null)

Returns the ID of the last inserted row, or the last value from a sequence object, depending on the underlying driver.

void
transactional(Closure $func)

Executes a function in a transaction.

void
setNestTransactionsWithSavepoints(boolean $nestTransactionsWithSavepoints)

Sets if nested transactions should use savepoints.

boolean
getNestTransactionsWithSavepoints()

Gets if nested transactions should use savepoints.

mixed
_getNestedTransactionSavePointName()

Returns the savepoint name to use for nested transactions are false if they are not supported "savepointFormat" parameter is not set

boolean
beginTransaction()

Starts a transaction by suspending auto-commit mode.

boolean
commit()

Commits the current transaction.

boolean
rollBack()

Cancels any database changes done during the current transaction.

void
createSavepoint(string $savepoint)

Creates a new savepoint.

void
releaseSavepoint(string $savepoint)

Releases the given savepoint.

void
rollbackSavepoint(string $savepoint)

Rolls back to the given savepoint.

getWrappedConnection()

Gets the wrapped driver connection.

getSchemaManager()

Gets the SchemaManager that can be used to inspect or change the database schema through the connection.

void
setRollbackOnly()

Marks the current transaction so that the only possible outcome for the transaction to be rolled back.

boolean
isRollbackOnly()

Checks whether the current transaction is marked for rollback only.

mixed
convertToDatabaseValue(mixed $value, string $type)

Converts a given value to its database representation according to the conversion rules of a specific DBAL mapping type.

mixed
convertToPHPValue(mixed $value, string $type)

Converts a given value to its PHP representation according to the conversion rules of a specific DBAL mapping type.

array
resolveParams(array $params, array $types)

Resolves the parameters to a format which can be displayed.

createQueryBuilder()

Creates a new instance of a SQL query builder.

bool
ping()

Ping the server

integer
getPortability()

No description

integer
getFetchCase()

No description

Details

__construct(array $params, Driver $driver, Configuration $config = null, EventManager $eventManager = null)

Initializes a new instance of the Connection class.

Parameters

array $params The connection parameters.
Driver $driver The driver to use.
Configuration $config The configuration, optional.
EventManager $eventManager The event manager, optional.

Exceptions

DBALException

array getParams()

Gets the parameters used during instantiation.

Return Value

array

string getDatabase()

Gets the name of the database this Connection is connected to.

Return Value

string

string|null getHost()

Gets the hostname of the currently connected database.

Return Value

string|null

mixed getPort()

Gets the port of the currently connected database.

Return Value

mixed

string|null getUsername()

Gets the username used by this connection.

Return Value

string|null

string|null getPassword()

Gets the password used by this connection.

Return Value

string|null

Driver getDriver()

Gets the DBAL driver instance.

Return Value

Driver

Configuration getConfiguration()

Gets the Configuration used by the Connection.

Return Value

Configuration

EventManager getEventManager()

Gets the EventManager used by the Connection.

Return Value

EventManager

AbstractPlatform getDatabasePlatform()

Gets the DatabasePlatform for the connection.

Return Value

AbstractPlatform

ExpressionBuilder getExpressionBuilder()

Gets the ExpressionBuilder for the connection.

Return Value

ExpressionBuilder

boolean connect()

Establishes the connection with the database.

Return Value

boolean TRUE if the connection was successfully established, FALSE if the connection is already open.

boolean isAutoCommit()

Returns the current auto-commit mode for this connection.

Return Value

boolean True if auto-commit mode is currently enabled for this connection, false otherwise.

See also

setAutoCommit

setAutoCommit(boolean $autoCommit)

Sets auto-commit mode for this connection.

If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback. By default, new connections are in auto-commit mode.

NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.

Parameters

boolean $autoCommit True to enable auto-commit mode; false to disable it.

See also

isAutoCommit

void setFetchMode(integer $fetchMode)

Sets the fetch mode.

Parameters

integer $fetchMode

Return Value

void

array fetchAssoc(string $statement, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the first row of the result as an associative array.

Parameters

string $statement The SQL query.
array $params The query parameters.
array $types The query parameter types.

Return Value

array

array fetchArray(string $statement, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the first row of the result as a numerically indexed array.

Parameters

string $statement The SQL query to be executed.
array $params The prepared statement params.
array $types The query parameter types.

Return Value

array

mixed fetchColumn(string $statement, array $params = array(), integer $column = 0, array $types = array())

Prepares and executes an SQL query and returns the value of a single column of the first row of the result.

Parameters

string $statement The SQL query to be executed.
array $params The prepared statement params.
integer $column The 0-indexed column number to retrieve.
array $types The query parameter types.

Return Value

mixed

boolean isConnected()

Whether an actual connection to the database is established.

Return Value

boolean

boolean isTransactionActive()

Checks whether a transaction is currently active.

Return Value

boolean TRUE if a transaction is currently active, FALSE otherwise.

integer delete(string $tableExpression, array $identifier, array $types = array())

Executes an SQL DELETE statement on a table.

Table expression and columns are not escaped and are not safe for user-input.

Parameters

string $tableExpression The expression of the table on which to delete.
array $identifier The deletion criteria. An associative array containing column-value pairs.
array $types The types of identifiers.

Return Value

integer The number of affected rows.

Exceptions

InvalidArgumentException

void close()

Closes the connection.

Return Value

void

integer setTransactionIsolation(integer $level)

Sets the transaction isolation level.

Parameters

integer $level The level to set.

Return Value

integer

integer getTransactionIsolation()

Gets the currently active transaction isolation level.

Return Value

integer The current transaction isolation level.

integer update(string $tableExpression, array $data, array $identifier, array $types = array())

Executes an SQL UPDATE statement on a table.

Table expression and columns are not escaped and are not safe for user-input.

Parameters

string $tableExpression The expression of the table to update quoted or unquoted.
array $data An associative array containing column-value pairs.
array $identifier The update criteria. An associative array containing column-value pairs.
array $types Types of the merged $data and $identifier arrays in that order.

Return Value

integer The number of affected rows.

integer insert(string $tableExpression, array $data, array $types = array())

Inserts a table row with specified data.

Table expression and columns are not escaped and are not safe for user-input.

Parameters

string $tableExpression The expression of the table to insert data into, quoted or unquoted.
array $data An associative array containing column-value pairs.
array $types Types of the inserted data.

Return Value

integer The number of affected rows.

string quoteIdentifier(string $str)

Quotes a string so it can be safely used as a table or column name, even if it is a reserved name.

Delimiting style depends on the underlying database platform that is being used.

NOTE: Just because you CAN use quoted identifiers does not mean you SHOULD use them. In general, they end up causing way more problems than they solve.

Parameters

string $str The name to be quoted.

Return Value

string The quoted name.

string quote(string $input, integer $type = null)

Quotes a given input parameter.

Parameters

string $input
integer $type

Return Value

string

array fetchAll(string $sql, array $params = array(), array $types = array())

Prepares and executes an SQL query and returns the result as an associative array.

Parameters

string $sql The SQL query.
array $params The query parameters.
array $types The query parameter types.

Return Value

array

Statement prepare(string $statement)

Prepares an SQL statement.

Parameters

string $statement The SQL statement to prepare.

Return Value

Statement

Exceptions

DBALException

Statement executeQuery(string $query, array $params = array(), array $types = array(), QueryCacheProfile $qcp = null)

Executes an, optionally parametrized, SQL query.

If the query is parametrized, a prepared statement is used. If an SQLLogger is configured, the execution is logged.

Parameters

string $query The SQL query to execute.
array $params The parameters to bind to the query, if any.
array $types The types the previous parameters are in.
QueryCacheProfile $qcp The query cache profile, optional.

Return Value

Statement The executed statement.

Exceptions

DBALException

ResultStatement executeCacheQuery(string $query, array $params, array $types, QueryCacheProfile $qcp)

Executes a caching query.

Parameters

string $query The SQL query to execute.
array $params The parameters to bind to the query, if any.
array $types The types the previous parameters are in.
QueryCacheProfile $qcp The query cache profile.

Return Value

ResultStatement

Exceptions

CacheException

array project(string $query, array $params, Closure $function)

Executes an, optionally parametrized, SQL query and returns the result, applying a given projection/transformation function on each row of the result.

Parameters

string $query The SQL query to execute.
array $params The parameters, if any.
Closure $function The transformation function that is applied on each row. The function receives a single parameter, an array, that represents a row of the result set.

Return Value

array The projected result of the query.

Statement query()

Executes an SQL statement, returning a result set as a Statement object.

Return Value

Statement

Exceptions

DBALException

integer executeUpdate(string $query, array $params = array(), array $types = array())

Executes an SQL INSERT/UPDATE/DELETE query with the given parameters and returns the number of affected rows.

This method supports PDO binding types as well as DBAL mapping types.

Parameters

string $query The SQL query.
array $params The query parameters.
array $types The parameter types.

Return Value

integer The number of affected rows.

Exceptions

DBALException

integer exec(string $statement)

Executes an SQL statement and return the number of affected rows.

Parameters

string $statement

Return Value

integer

Exceptions

DBALException

integer getTransactionNestingLevel()

Returns the current transaction nesting level.

Return Value

integer The nesting level. A value of 0 means there's no active transaction.

string|null errorCode()

Fetches the SQLSTATE associated with the last database operation.

Return Value

string|null The error code, or null if no operation has been run on the database handle.

array errorInfo()

Fetches extended error information associated with the last database operation.

Return Value

array

string lastInsertId(string|null $seqName = null)

Returns the ID of the last inserted row, or the last value from a sequence object, depending on the underlying driver.

Note: This method may not return a meaningful or consistent result across different drivers, because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY columns or sequences.

Parameters

string|null $seqName Name of the sequence object from which the ID should be returned.

Return Value

string

void transactional(Closure $func)

Executes a function in a transaction.

The function gets passed this Connection instance as an (optional) parameter.

If an exception occurs during execution of the function or transaction commit, the transaction is rolled back and the exception re-thrown.

Parameters

Closure $func The function to execute transactionally.

Return Value

void

Exceptions

Exception

void setNestTransactionsWithSavepoints(boolean $nestTransactionsWithSavepoints)

Sets if nested transactions should use savepoints.

Parameters

boolean $nestTransactionsWithSavepoints

Return Value

void

Exceptions

ConnectionException

boolean getNestTransactionsWithSavepoints()

Gets if nested transactions should use savepoints.

Return Value

boolean

protected mixed _getNestedTransactionSavePointName()

Returns the savepoint name to use for nested transactions are false if they are not supported "savepointFormat" parameter is not set

Return Value

mixed A string with the savepoint name or false.

boolean beginTransaction()

Starts a transaction by suspending auto-commit mode.

Return Value

boolean TRUE on success or FALSE on failure.

boolean commit()

Commits the current transaction.

Return Value

boolean TRUE on success or FALSE on failure.

Exceptions

ConnectionException If the commit failed due to no active transaction or because the transaction was marked for rollback only.

boolean rollBack()

Cancels any database changes done during the current transaction.

This method can be listened with onPreTransactionRollback and onTransactionRollback eventlistener methods.

Return Value

boolean TRUE on success or FALSE on failure.

Exceptions

ConnectionException If the rollback operation failed.

void createSavepoint(string $savepoint)

Creates a new savepoint.

Parameters

string $savepoint The name of the savepoint to create.

Return Value

void

Exceptions

ConnectionException

void releaseSavepoint(string $savepoint)

Releases the given savepoint.

Parameters

string $savepoint The name of the savepoint to release.

Return Value

void

Exceptions

ConnectionException

void rollbackSavepoint(string $savepoint)

Rolls back to the given savepoint.

Parameters

string $savepoint The name of the savepoint to rollback to.

Return Value

void

Exceptions

ConnectionException

Connection getWrappedConnection()

Gets the wrapped driver connection.

Return Value

Connection

AbstractSchemaManager getSchemaManager()

Gets the SchemaManager that can be used to inspect or change the database schema through the connection.

Return Value

AbstractSchemaManager

void setRollbackOnly()

Marks the current transaction so that the only possible outcome for the transaction to be rolled back.

Return Value

void

Exceptions

ConnectionException If no transaction is active.

boolean isRollbackOnly()

Checks whether the current transaction is marked for rollback only.

Return Value

boolean

Exceptions

ConnectionException If no transaction is active.

mixed convertToDatabaseValue(mixed $value, string $type)

Converts a given value to its database representation according to the conversion rules of a specific DBAL mapping type.

Parameters

mixed $value The value to convert.
string $type The name of the DBAL mapping type.

Return Value

mixed The converted value.

mixed convertToPHPValue(mixed $value, string $type)

Converts a given value to its PHP representation according to the conversion rules of a specific DBAL mapping type.

Parameters

mixed $value The value to convert.
string $type The name of the DBAL mapping type.

Return Value

mixed The converted type.

array resolveParams(array $params, array $types)

Resolves the parameters to a format which can be displayed.

Parameters

array $params
array $types

Return Value

array

QueryBuilder createQueryBuilder()

Creates a new instance of a SQL query builder.

Return Value

QueryBuilder

bool ping()

Ping the server

When the server is not available the method returns FALSE. It is responsibility of the developer to handle this case and abort the request or reconnect manually:

Return Value

bool

integer getPortability()

Return Value

integer

integer getFetchCase()

Return Value

integer