Class Connection

Represents a connection with a database server.

Namespace: Cake\Database

Property Summary

$_config protected

array

Contains the configuration params for this connection.
$_driver protected

Cake\Database\Driver

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

bool

Whether to log queries generated during this connection.
$_logger protected

Cake\Database\Log\QueryLogger

Logger object instance.
$_schemaCollection protected

Cake\Database\Schema\Collection

The schema collection object
$_transactionLevel protected

int

Contains how many nested transactions have been started.
$_transactionStarted protected

bool

Whether a transaction is active in this connection.
$_useSavePoints protected

bool

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

Method Summary

__construct() public

Constructor.
__debugInfo() public

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

Destructor
_newLogger() protected

Returns a new statement object that will log the activity for the passed original statement instance.
begin() public

Starts a new transaction.
cacheMetadata() public

Enables or disables metadata caching for this connection
cast() public

Converts a give value to a suitable database value based on type and return relevant internal statement type
commit() public

Commits current transaction.
compileQuery() public

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.
createSavePoint() public

Creates a new save point for nested transactions.
delete() public

Executes a DELETE statement on the specified table.
disableConstraints() public

Run an operation with constraints disabled.
disableForeignKeys() public

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.
enableForeignKeys() public

Run driver specific SQL to enable foreign key checks.
execute() public

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

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.
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.
matchTypes() public

Matches columns to corresponding types
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.
quoteIdentifier() public

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

Releases a save point by its name.
rollback() public

Rollback current transaction.
rollbackSavepoint() public

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.
schemaCollection() public

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

Returns whether the driver supports adding or dropping constraints to already created tables.
supportsQuoting() public

Checks if the driver supports quoting.
transactional() public

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.
useSavePoints() public

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.

Method Detail

__construct() ¶ public

__construct(array $config)

Constructor.

Parameters

array $config: configuration for connecting to database

__debugInfo() ¶ public

__debugInfo(): array

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

Returns

array

__destruct() ¶ public

__destruct()

Destructor

Disconnects the driver to release the connection.

_newLogger() ¶ protected

_newLogger(Cake\Database\StatementInterface $statement): Cake\Database\Log\LoggingStatement

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() ¶ public

begin(): void

Starts a new transaction.

Returns

void

cacheMetadata() ¶ public

cacheMetadata(bool|string $cache): void

Enables or disables metadata caching for this connection

Changing this setting will not modify existing schema collections objects.

Parameters

bool|string $cache: Either boolean false to disable meta dataing caching, or true to use _cake_model_ or the name of the cache config to use.

Returns

void

cast() ¶ public

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

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

commit() ¶ public

commit(): bool

Commits current transaction.

Returns

bool

true on success, false otherwise

compileQuery() ¶ public

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

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() ¶ public

config(): array

Get the configuration data used to create the connection.

Returns

array

configName() ¶ public

configName(): string

Get the configuration name for this connection.

Returns

string

connect() ¶ public

connect(): bool

Connects to the configured database.

Returns

bool

true on success or false if already connected.

Throws

Cake\Database\Exception\MissingConnectionException
if credentials are invalid

createSavePoint() ¶ public

createSavePoint(string $name): void

Creates a new save point for nested transactions.

Parameters

string $name: The save point name.

Returns

void

delete() ¶ public

delete(string $table, array $conditions = [], array $types = []): Cake\Database\StatementInterface

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() ¶ public

disableConstraints(callable $callback): mixed

Run an operation with constraints disabled.

Example:

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

Parameters

callable $callback

Returns

mixed

disableForeignKeys() ¶ public

disableForeignKeys(): void

Run driver specific SQL to disable foreign key checks.

Returns

void

disconnect() ¶ public

disconnect(): void

Disconnects from database server.

Returns

void

driver() ¶ public

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

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.

Parameters

Cake\Database\Driver|string|null $driver optional: 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() ¶ public

enableForeignKeys(): void

Run driver specific SQL to enable foreign key checks.

Returns

void

execute() ¶ public

execute(string $query, array $params = [], array $types = []): Cake\Database\StatementInterface

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

inTransaction() ¶ public

inTransaction(): bool

Checks if a transaction is running.

Returns

bool

True if a transaction is running else false.

insert() ¶ public

insert(string $table, array $data, array $types = []): Cake\Database\StatementInterface

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() ¶ public

isConnected(): bool

Returns whether connection to database server was already established.

Returns

bool

log() ¶ public

log(string $sql): void

Logs a Query string using the configured logger object.

Parameters

string $sql: string to be logged

Returns

void

logQueries() ¶ public

logQueries(bool|null $enable = null): bool

Enables or disables query logging for this connection.

Parameters

bool|null $enable optional

Returns

bool

logger() ¶ public

logger(object|null $instance = null): object

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

Parameters

object|null $instance optional

Returns

object

matchTypes() ¶ public

matchTypes(array $columns, array $types): array

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

newQuery() ¶ public

newQuery(): Cake\Database\Query

Create a new Query instance for this connection.

Returns

Cake\Database\Query

prepare() ¶ public

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

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() ¶ public

query(string $sql): Cake\Database\StatementInterface

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

Parameters

string $sql: The SQL query to execute.

Returns

Cake\Database\StatementInterface

quote() ¶ public

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

Quotes value to be used safely in database query.

Parameters

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

Returns

string

Quoted value

quoteIdentifier() ¶ public

quoteIdentifier(string $identifier): string

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() ¶ public

releaseSavePoint(string $name): void

Releases a save point by its name.

Parameters

string $name: The save point name.

Returns

void

rollback() ¶ public

rollback(): bool

Rollback current transaction.

Returns

bool

rollbackSavepoint() ¶ public

rollbackSavepoint(string $name): void

Rollback a save point by its name.

Parameters

string $name: The save point name.

Returns

void

run() ¶ public

run(Cake\Database\Query $query): Cake\Database\StatementInterface

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() ¶ public

schemaCollection(Cake\Database\Schema\Collection|null $collection = null): Cake\Database\Schema\Collection

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

Parameters

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

Returns

Cake\Database\Schema\Collection

supportsDynamicConstraints() ¶ public

supportsDynamicConstraints(): bool

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

Returns

bool

true if driver supports dynamic constraints

supportsQuoting() ¶ public

supportsQuoting(): bool

Checks if the driver supports quoting.

Returns

bool

transactional() ¶ public

transactional(callable $callback): mixed

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

Returns

mixed

update() ¶ public

update(string $table, array $data, array $conditions = [], array $types = []): Cake\Database\StatementInterface

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() ¶ public

useSavePoints(bool|null $enable = null): bool

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

Parameters

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

Returns

bool

true if enabled, false otherwise

Property Detail

`$_config` ¶ protected

Contains the configuration params for this connection.

Type

array

`$_driver` ¶ protected

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

Type

Cake\Database\Driver

`$_logQueries` ¶ protected

Whether to log queries generated during this connection.

Type

bool

`$_logger` ¶ protected

Logger object instance.

Type

Cake\Database\Log\QueryLogger

`$_schemaCollection` ¶ protected

The schema collection object

Type

Cake\Database\Schema\Collection

`$_transactionLevel` ¶ protected

Contains how many nested transactions have been started.

Type

int

`$_transactionStarted` ¶ protected

Whether a transaction is active in this connection.

Type

bool

`$_useSavePoints` ¶ protected

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

Type

bool

Namespaces

Class Connection

Property Summary

Method Summary

__construct() public

__debugInfo() public

__destruct() public

_newLogger() protected

begin() public

cacheMetadata() public

cast() public

commit() public

compileQuery() public

config() public

configName() public

connect() public

createSavePoint() public

delete() public

disableConstraints() public

disableForeignKeys() public

disconnect() public

driver() public

enableForeignKeys() public

execute() public

inTransaction() public

insert() public

isConnected() public

log() public

logQueries() public

logger() public

matchTypes() public

newQuery() public

prepare() public

query() public

quote() public

quoteIdentifier() public

releaseSavePoint() public

rollback() public

rollbackSavepoint() public

run() public

schemaCollection() public

supportsDynamicConstraints() public

supportsQuoting() public

transactional() public

update() public

useSavePoints() public

Method Detail

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__destruct() ¶ public

_newLogger() ¶ protected

Parameters

Returns

begin() ¶ public

Returns

cacheMetadata() ¶ public

Parameters

Returns

cast() ¶ public

Parameters

Returns

commit() ¶ public

Returns

compileQuery() ¶ public

Parameters

Returns

config() ¶ public

Returns

configName() ¶ public

Returns

connect() ¶ public

Returns

Throws

createSavePoint() ¶ public

Parameters

Returns

delete() ¶ public

Parameters