Class Connection

Represents a connection with a database server.

Cake\Database\Connection implements Cake\Datasource\ConnectionInterface uses Cake\Database\TypeConverterTrait
Namespace: Cake\Database
Location: Database/Connection.php

Properties summary

Method Summary

  • __construct() public
    Constructor.
  • __debugInfo() public

    Returns an array that can be used to describe the internal state of this object.

  • _newLogger() protected

    Returns a new statement object that will log the activity for the passed original statement instance.

  • begin() public
    Starts a new transaction.
  • Enables or disables metadata caching for this connection
  • commit() public
    Commits current transaction.
  • Compiles a Query object into a SQL string according to the dialect for this connection's driver

  • config() public
    Get the configuration data used to create the connection.
  • configName() public
    Get the configuration name for this connection.
  • connect() public
    Connects to the configured database.
  • Creates a new save point for nested transactions.
  • delete() public
    Executes a DELETE statement on the specified table.
  • Run an operation with constraints disabled.
  • Run driver specific SQL to disable foreign key checks.
  • disconnect() public
    Disconnects from database server.
  • driver() public

    Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.

  • Run driver specific SQL to enable foreign key checks.
  • Enables/disables the usage of savepoints, enables only if driver the allows it.
  • execute() public

    Executes a query using $params for interpolating values and $types as a hint for each those params.

  • getDriver() public
    Gets the driver instance.
  • getLogger() public
    Gets the logger object
  • Gets a Schema\Collection object for this connection.
  • Checks if a transaction is running.
  • insert() public
    Executes an INSERT query on the specified table.
  • isConnected() public
    Returns whether connection to database server was already established.
  • Returns whether this connection is using savepoints for nested transactions
  • log() public
    Logs a Query string using the configured logger object.
  • logQueries() public
    Enables or disables query logging for this connection.
  • logger() public

    Sets the logger object instance. When called with no arguments it returns the currently setup logger instance.

  • newQuery() public
    Create a new Query instance for this connection.
  • prepare() public
    Prepares a SQL statement to be executed.
  • query() public
    Executes a SQL statement and returns the Statement object as result.
  • quote() public
    Quotes value to be used safely in database query.
  • Quotes a database identifier (a column name, table name, etc..) to be used safely in queries without the risk of using reserved words.

  • Releases a save point by its name.
  • rollback() public
    Rollback current transaction.
  • Rollback a save point by its name.
  • run() public

    Executes the provided query after compiling it for the specific driver dialect and returns the executed Statement object.

  • Gets or sets a Schema\Collection object for this connection.
  • setDriver() public

    Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.

  • setLogger() public
    Sets a logger
  • Sets a Schema\Collection object for this connection.
  • Returns whether the driver supports adding or dropping constraints to already created tables.

  • Checks if the driver supports quoting.
  • Executes a callable function inside a transaction, if any exception occurs while executing the passed callable, the transaction will be rolled back If the result of the callable function is false, the transaction will also be rolled back. Otherwise the transaction is committed after executing the callback.

  • update() public
    Executes an UPDATE statement on the specified table.
  • Returns whether this connection is using savepoints for nested transactions If a boolean is passed as argument it will enable/disable the usage of savepoints only if driver the allows it.

  • Returns whether some nested transaction has been already rolled back.

Method Detail

__construct()source public

__construct( array $config )

Constructor.

Parameters

array $config
configuration for connecting to database

__debugInfo()source public

__debugInfo( )

Returns an array that can be used to describe the internal state of this object.

Returns

array

_newLogger()source protected

_newLogger( Cake\Database\StatementInterface $statement )

Returns a new statement object that will log the activity for the passed original statement instance.

Parameters

Cake\Database\StatementInterface $statement
the instance to be decorated

Returns

Cake\Database\Log\LoggingStatement

begin()source public

begin( )

Starts a new transaction.

cacheMetadata()source public

cacheMetadata( boolean|string $cache )

Enables or disables metadata caching for this connection

Changing this setting will not modify existing schema collections objects.

Parameters

boolean|string $cache

Either boolean false to disable metadata caching, or true to use _cake_model_ or the name of the cache config to use.

commit()source public

commit( )

Commits current transaction.

Returns

boolean
true on success, false otherwise

compileQuery()source public

compileQuery( Cake\Database\Query $query , Cake\Database\ValueBinder $generator )

Compiles a Query object into a SQL string according to the dialect for this connection's driver

Parameters

Cake\Database\Query $query
The query to be compiled
Cake\Database\ValueBinder $generator
The placeholder generator to use

Returns

string

config()source public

config( )

Get the configuration data used to create the connection.

Returns

array

Implementation of

Cake\Datasource\ConnectionInterface::config()

configName()source public

configName( )

Get the configuration name for this connection.

Returns

string

Implementation of

Cake\Datasource\ConnectionInterface::configName()

connect()source public

connect( )

Connects to the configured database.

Returns

boolean
true, if the connection was already established or the attempt was successful.

Throws

Cake\Database\Exception\MissingConnectionException
if credentials are invalid.

createSavePoint()source public

createSavePoint( string $name )

Creates a new save point for nested transactions.

Parameters

string $name
The save point name.

delete()source public

delete( string $table , array $conditions [] , array $types [] )

Executes a DELETE statement on the specified table.

Parameters

string $table
the table to delete rows from
array $conditions optional []
conditions to be set for delete statement
array $types optional []
list of associative array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

disableConstraints()source public

disableConstraints( callable $callback )

Run an operation with constraints disabled.

Example:

$connection->disableConstraints(function ($connection) {
  $connection->newQuery()->delete('users')->execute();
});

Parameters

callable $callback
$operation The callback to execute within a transaction.

Returns

mixed
The return value of the callback.

Throws

Exception

Will re-throw any exception raised in $callback after rolling back the transaction.


Implementation of

Cake\Datasource\ConnectionInterface::disableConstraints()

disableForeignKeys()source public

disableForeignKeys( )

Run driver specific SQL to disable foreign key checks.

disconnect()source public

disconnect( )

Disconnects from database server.

driver()source public

driver( Cake\Database\Driver|string|null $driver null , array $config [] )

Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.

If no params are passed it will return the current driver instance.

Deprecated

3.4.0 Use setDriver()/getDriver() instead.

Parameters

Cake\Database\Driver|string|null $driver optional null
The driver instance to use.
array $config optional []
Either config for a new driver or null.

Returns

Cake\Database\Driver

Throws

Cake\Database\Exception\MissingDriverException
When a driver class is missing.
Cake\Database\Exception\MissingExtensionException
When a driver's PHP extension is missing.

enableForeignKeys()source public

enableForeignKeys( )

Run driver specific SQL to enable foreign key checks.

enableSavePoints()source public

enableSavePoints( boolean $enable )

Enables/disables the usage of savepoints, enables only if driver the allows it.

If you are trying to enable this feature, make sure you check the return value of this function to verify it was enabled successfully.

Example:

$connection->enableSavePoints(true) Returns true if drivers supports save points, false otherwise $connection->enableSavePoints(false) Disables usage of savepoints and returns false

Parameters

boolean $enable
Whether or not save points should be used.

Returns


$this

execute()source public

execute( string $query , array $params [] , array $types [] )

Executes a query using $params for interpolating values and $types as a hint for each those params.

Parameters

string $query
SQL to be executed and interpolated with $params
array $params optional []
list or associative array of params to be interpolated in $query as values
array $types optional []
list or associative array of types to be used for casting values in query

Returns

Cake\Database\StatementInterface
executed statement

getDriver()source public

getDriver( )

Gets the driver instance.

Returns

Cake\Database\Driver

getLogger()source public

getLogger( )

Gets the logger object

Returns

object
logger instance

getSchemaCollection()source public

getSchemaCollection( )

Gets a Schema\Collection object for this connection.

Returns

Cake\Database\Schema\Collection

inTransaction()source public

inTransaction( )

Checks if a transaction is running.

Returns

boolean
True if a transaction is running else false.

insert()source public

insert( string $table , array $data , array $types [] )

Executes an INSERT query on the specified table.

Parameters

string $table
the table to insert values in
array $data
values to be inserted
array $types optional []
list of associative array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

isConnected()source public

isConnected( )

Returns whether connection to database server was already established.

Returns

boolean

isSavePointsEnabled()source public

isSavePointsEnabled( )

Returns whether this connection is using savepoints for nested transactions

Returns

boolean
true if enabled, false otherwise

log()source public

log( string $sql )

Logs a Query string using the configured logger object.

Parameters

string $sql
string to be logged

logQueries()source public

logQueries( boolean|null $enable null )

Enables or disables query logging for this connection.

Parameters

boolean|null $enable optional null

whether to turn logging on or disable it. Use null to read current value.

Returns

boolean

Implementation of

Cake\Datasource\ConnectionInterface::logQueries()

logger()source public

logger( object|null $instance null )

Sets the logger object instance. When called with no arguments it returns the currently setup logger instance.

Deprecated

3.5.0 Use getLogger() and setLogger() instead.

Parameters

object|null $instance optional null
logger object instance

Returns

object
logger instance

Implementation of

Cake\Datasource\ConnectionInterface::logger()

newQuery()source public

newQuery( )

Create a new Query instance for this connection.

Returns

Cake\Database\Query

prepare()source public

prepare( string|Cake\Database\Query $sql )

Prepares a SQL statement to be executed.

Parameters

string|Cake\Database\Query $sql
The SQL to convert into a prepared statement.

Returns

Cake\Database\StatementInterface

query()source public

query( string $sql )

Executes a SQL statement and returns the Statement object as result.

Parameters

string $sql
The SQL query to execute.

Returns

Cake\Database\StatementInterface

quote()source public

quote( mixed $value , string|null $type null )

Quotes value to be used safely in database query.

Parameters

mixed $value
The value to quote.
string|null $type optional null
Type to be used for determining kind of quoting to perform

Returns

string
Quoted value

quoteIdentifier()source public

quoteIdentifier( string $identifier )

Quotes a database identifier (a column name, table name, etc..) to be used safely in queries without the risk of using reserved words.

Parameters

string $identifier
The identifier to quote.

Returns

string

releaseSavePoint()source public

releaseSavePoint( string $name )

Releases a save point by its name.

Parameters

string $name
The save point name.

rollback()source public

rollback( boolean|null $toBeginning null )

Rollback current transaction.

Parameters

boolean|null $toBeginning optional null

Whether or not the transaction should be rolled back to the beginning of it. Defaults to false if using savepoints, or true if not.

Returns

boolean

rollbackSavepoint()source public

rollbackSavepoint( string $name )

Rollback a save point by its name.

Parameters

string $name
The save point name.

run()source public

run( Cake\Database\Query $query )

Executes the provided query after compiling it for the specific driver dialect and returns the executed Statement object.

Parameters

Cake\Database\Query $query
The query to be executed

Returns

Cake\Database\StatementInterface
executed statement

schemaCollection()source public

schemaCollection( Cake\Database\Schema\Collection $collection null )

Gets or sets a Schema\Collection object for this connection.

Deprecated

3.4.0 Use setSchemaCollection()/getSchemaCollection()

Parameters

Cake\Database\Schema\Collection $collection optional null
The schema collection object

Returns

Cake\Database\Schema\Collection

setDriver()source public

setDriver( Cake\Database\Driver|string $driver , array $config [] )

Sets the driver instance. If a string is passed it will be treated as a class name and will be instantiated.

Parameters

Cake\Database\Driver|string $driver
The driver instance to use.
array $config optional []
Config for a new driver.

Returns


$this

Throws

Cake\Database\Exception\MissingDriverException
When a driver class is missing.
Cake\Database\Exception\MissingExtensionException
When a driver's PHP extension is missing.

setLogger()source public

setLogger( object $logger )

Sets a logger

Parameters

object $logger
Logger object

Returns


$this

setSchemaCollection()source public

setSchemaCollection( Cake\Database\Schema\Collection $collection )

Sets a Schema\Collection object for this connection.

Parameters

Cake\Database\Schema\Collection $collection
The schema collection object

Returns


$this

supportsDynamicConstraints()source public

supportsDynamicConstraints( )

Returns whether the driver supports adding or dropping constraints to already created tables.

Returns

boolean
true if driver supports dynamic constraints

supportsQuoting()source public

supportsQuoting( )

Checks if the driver supports quoting.

Returns

boolean

transactional()source public

transactional( callable $callback )

Executes a callable function inside a transaction, if any exception occurs while executing the passed callable, the transaction will be rolled back If the result of the callable function is false, the transaction will also be rolled back. Otherwise the transaction is committed after executing the callback.

Example:

$connection->transactional(function ($connection) {
  $connection->newQuery()->delete('users')->execute();
});

Parameters

callable $callback
$transaction The callback to execute within a transaction.

Returns

mixed
The return value of the callback.

Throws

Exception

Will re-throw any exception raised in $callback after rolling back the transaction.


Implementation of

Cake\Datasource\ConnectionInterface::transactional()

update()source public

update( string $table , array $data , array $conditions [] , array $types [] )

Executes an UPDATE statement on the specified table.

Parameters

string $table
the table to update rows from
array $data
values to be updated
array $conditions optional []
conditions to be set for update statement
array $types optional []
list of associative array containing the types to be used for casting

Returns

Cake\Database\StatementInterface

useSavePoints()source public

useSavePoints( boolean|null $enable null )

Returns whether this connection is using savepoints for nested transactions If a boolean is passed as argument it will enable/disable the usage of savepoints only if driver the allows it.

If you are trying to enable this feature, make sure you check the return value of this function to verify it was enabled successfully.

Example:

$connection->useSavePoints(true) Returns true if drivers supports save points, false otherwise $connection->useSavePoints(false) Disables usage of savepoints and returns false $connection->useSavePoints() Returns current status

Deprecated

3.4.0 Use enableSavePoints()/isSavePointsEnabled() instead.

Parameters

boolean|null $enable optional null
Whether or not save points should be used.

Returns

boolean
true if enabled, false otherwise

wasNestedTransactionRolledback()source protected

wasNestedTransactionRolledback( )

Returns whether some nested transaction has been already rolled back.

Returns

boolean

Methods used from Cake\Database\TypeConverterTrait

cast()source public

cast( mixed $value , Cake\Database\Type|string $type )

Converts a give value to a suitable database value based on type and return relevant internal statement type

Parameters

mixed $value
The value to cast
Cake\Database\Type|string $type
The type name or type instance to use.

Returns

array
list containing converted value and internal type

matchTypes()source public

matchTypes( array $columns , array $types )

Matches columns to corresponding types

Both $columns and $types should either be numeric based or string key based at the same time.

Parameters

array $columns
list or associative array of columns and parameters to be bound with types
array $types
list or associative array of types

Returns

array

Magic methods inherited from Cake\Datasource\ConnectionInterface

execute(), getLogger(), lastInsertId(), newQuery(), prepare(), quote(), schemaCollection(), supportsDynamicConstraints()

Properties detail

$_configsource

protected array

Contains the configuration params for this connection.

$_driversource

protected Cake\Database\Driver

Driver object, responsible for creating the real connection and provide specific SQL dialect.

$_logQueriessource

protected boolean

Whether to log queries generated during this connection.

false

$_loggersource

protected Cake\Database\Log\QueryLogger|null

Logger object instance.

$_schemaCollectionsource

protected Cake\Database\Schema\Collection|null

The schema collection object

$_transactionLevelsource

protected integer

Contains how many nested transactions have been started.

$_transactionStartedsource

protected boolean

Whether a transaction is active in this connection.

false

$_useSavePointssource

protected boolean

Whether this connection can and should use savepoints for nested transactions.

false

$nestedTransactionRollbackExceptionsource

protected Cake\Database\Exception\NestedTransactionRollbackException|null

NestedTransactionRollbackException object instance, will be stored if the rollback method is called in some nested transaction.

© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.4/class-Cake.Database.Connection.html