CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 4.6 Strawberry API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 4.6
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
    • Core
    • Database
      • Driver
      • Exception
      • Expression
      • Log
      • Query
      • Retry
      • Schema
      • Statement
      • Type
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

Class Connection

Represents a connection with a database server.

Namespace: Cake\Database

Constants

  • string
    ROLE_READ ¶
    'read'
  • string
    ROLE_WRITE ¶
    'write'

Property Summary

  • $_config protected
    array<string, mixed>

    Contains the configuration params for this connection.

  • $_logQueries protected
    bool

    Whether to log queries generated during this connection.

  • $_logger protected
    Psr\Log\LoggerInterface|null

    Logger object instance.

  • $_schemaCollection protected
    Cake\Database\Schema\CollectionInterface|null

    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.

  • $cacher protected
    Psr\SimpleCache\CacheInterface|null

    Cacher object instance.

  • $nestedTransactionRollbackException protected
    Cake\Database\Exception\NestedTransactionRollbackException|null

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

  • $readDriver protected
    Cake\Database\DriverInterface
  • $writeDriver protected
    Cake\Database\DriverInterface

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 deprecated

    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 deprecated

    Connects to the configured database.

  • createDriver() protected

    Creates driver from name, class name or instance.

  • createDrivers() protected

    Creates read and write drivers.

  • createSavePoint() public

    Creates a new save point for nested transactions.

  • delete() public

    Executes a DELETE statement on the specified table.

  • deleteQuery() public

    Create a new DeleteQuery instance for this connection.

  • disableConstraints() public

    Run an operation with constraints disabled.

  • disableForeignKeys() public

    Run driver specific SQL to disable foreign key checks.

  • disableQueryLogging() public deprecated

    Disable query logging

  • disableSavePoints() public

    Disables the usage of savepoints.

  • disconnect() public deprecated

    Disconnects from database server.

  • enableForeignKeys() public

    Run driver specific SQL to enable foreign key checks.

  • enableQueryLogging() public deprecated

    Enable/disable query logging

  • enableSavePoints() public

    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.

  • getCacher() public

    Get a cacher.

  • getDisconnectRetry() public

    Get the retry wrapper object that is allows recovery from server disconnects while performing certain database actions, such as executing a query.

  • getDriver() public

    Gets the driver instance.

  • getLogger() public

    Gets the logger object

  • getSchemaCollection() public

    Gets a Schema\Collection object for this connection.

  • inTransaction() public

    Checks if a transaction is running.

  • insert() public

    Executes an INSERT query on the specified table.

  • insertQuery() public

    Create a new InsertQuery instance for this connection.

  • isConnected() public deprecated

    Returns whether connection to database server was already established.

  • isQueryLoggingEnabled() public deprecated

    Check if query logging is enabled.

  • isSavePointsEnabled() public

    Returns whether this connection is using savepoints for nested transactions

  • log() public

    Logs a Query string using the configured logger object.

  • matchTypes() public

    Matches columns to corresponding types

  • newQuery() public deprecated

    Create a new Query instance for this connection.

  • prepare() public deprecated

    Prepares a SQL statement to be executed.

  • query() public deprecated

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

  • quote() public deprecated

    Quotes value to be used safely in database query.

  • quoteIdentifier() public deprecated

    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.

  • role() public

    Returns the connection role: read or write.

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

  • selectQuery() public

    Create a new SelectQuery instance for this connection.

  • setCacher() public

    Set a cacher.

  • setDriver() public deprecated

    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

  • setSchemaCollection() public

    Sets a Schema\Collection object for this connection.

  • supportsDynamicConstraints() public deprecated

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

  • supportsQuoting() public deprecated

    Checks if using quote() is supported.

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

  • updateQuery() public

    Create a new UpdateQuery instance for this connection.

  • wasNestedTransactionRolledback() protected

    Returns whether some nested transaction has been already rolled back.

Method Detail

__construct() ¶ public

__construct(array<string, mixed> $config)

Constructor.

Available options:

  • driver Sort name or FCQN for driver.
  • log Boolean indicating whether to use query logging.
  • name Connection name.
  • cacheMetaData Boolean indicating whether metadata (datasource schemas) should be cached. If set to a string it will be used as the name of cache config to use.
  • cacheKeyPrefix Custom prefix to use when generation cache keys. Defaults to connection name.
Parameters
array<string, mixed> $config

Configuration array.

__debugInfo() ¶ public

__debugInfo(): array<string, mixed>

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

Returns
array<string, mixed>

__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(string|bool $cache): void

Enables or disables metadata caching for this connection

Changing this setting will not modify existing schema collections objects.

Parameters
string|bool $cache

Either boolean false to disable metadata 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\TypeInterface|string|int $type = 'string'): 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\TypeInterface|string|int $type optional

The type name or type instance to use.

Returns
array

commit() ¶ public

commit(): bool

Commits current transaction.

Returns
bool

compileQuery() ¶ public

compileQuery(Cake\Database\Query $query, Cake\Database\ValueBinder $binder): 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 $binder

Value binder

Returns
string

config() ¶ public

config(): array<string, mixed>

Get the configuration data used to create the connection.

Returns
array<string, mixed>

configName() ¶ public

configName(): string

Get the configuration name for this connection.

Returns
string

connect() ¶ public

connect(): bool

Connects to the configured database.

Returns
bool
Throws
Cake\Database\Exception\MissingConnectionException
If database connection could not be established.

createDriver() ¶ protected

createDriver(Cake\Database\DriverInterface|string $name, array $config): Cake\Database\DriverInterface

Creates driver from name, class name or instance.

Parameters
Cake\Database\DriverInterface|string $name

Driver name, class name or instance.

array $config

Driver config if $name is not an instance.

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

createDrivers() ¶ protected

createDrivers(array $config): array<string, \Cake\Database\DriverInterface>

Creates read and write drivers.

Parameters
array $config

Connection config

Returns
array<string, \Cake\Database\DriverInterface>

createSavePoint() ¶ public

createSavePoint(string|int $name): void

Creates a new save point for nested transactions.

Parameters
string|int $name

Save point name or id

Returns
void

delete() ¶ public

delete(string $table, array $conditions = [], array<string> $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<string> $types optional

list of associative array containing the types to be used for casting

Returns
Cake\Database\StatementInterface

deleteQuery() ¶ public

deleteQuery(string|null $table = null, array $conditions = [], array<string, string> $types = []): Cake\Database\Query\DeleteQuery

Create a new DeleteQuery instance for this connection.

Parameters
string|null $table optional

The table to delete rows from.

array $conditions optional

Conditions to be set for the delete statement.

array<string, string> $types optional

Associative array containing the types to be used for casting.

Returns
Cake\Database\Query\DeleteQuery

disableConstraints() ¶ public

disableConstraints(callable $callback): mixed

Run an operation with constraints disabled.

Constraints should be re-enabled after the callback succeeds/fails.

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

disableQueryLogging() ¶ public

disableQueryLogging(): $this

Disable query logging

Returns
$this

disableSavePoints() ¶ public

disableSavePoints(): $this

Disables the usage of savepoints.

Returns
$this

disconnect() ¶ public

disconnect(): void

Disconnects from database server.

Returns
void

enableForeignKeys() ¶ public

enableForeignKeys(): void

Run driver specific SQL to enable foreign key checks.

Returns
void

enableQueryLogging() ¶ public

enableQueryLogging(bool $enable = true): $this

Enable/disable query logging

Parameters
bool $enable optional

Enable/disable query logging

Returns
$this

enableSavePoints() ¶ public

enableSavePoints(bool $enable = true): $this

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 isSavePointsEnabled() to verify that savepoints were enabled successfully.

Parameters
bool $enable optional

Whether save points should be used.

Returns
$this

execute() ¶ public

execute(string $sql, 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 $sql

SQL to be executed and interpolated with $params

array $params optional

list or associative array of params to be interpolated in $sql as values

array $types optional

list or associative array of types to be used for casting values in query

Returns
Cake\Database\StatementInterface

getCacher() ¶ public

getCacher(): Psr\SimpleCache\CacheInterface

Get a cacher.

Returns
Psr\SimpleCache\CacheInterface

getDisconnectRetry() ¶ public

getDisconnectRetry(): Cake\Core\Retry\CommandRetry

Get the retry wrapper object that is allows recovery from server disconnects while performing certain database actions, such as executing a query.

Returns
Cake\Core\Retry\CommandRetry

getDriver() ¶ public

getDriver(string $role = self::ROLE_WRITE): Cake\Database\DriverInterface

Gets the driver instance.

Parameters
string $role optional

Connection role ('read' or 'write')

Returns
Cake\Database\DriverInterface

getLogger() ¶ public

getLogger(): Psr\Log\LoggerInterface

Gets the logger object

Returns
Psr\Log\LoggerInterface

getSchemaCollection() ¶ public

getSchemaCollection(): Cake\Database\Schema\CollectionInterface

Gets a Schema\Collection object for this connection.

Returns
Cake\Database\Schema\CollectionInterface

inTransaction() ¶ public

inTransaction(): bool

Checks if a transaction is running.

Returns
bool

insert() ¶ public

insert(string $table, array $values, array<int|string, string> $types = []): Cake\Database\StatementInterface

Executes an INSERT query on the specified table.

Parameters
string $table

the table to insert values in

array $values

values to be inserted

array<int|string, string> $types optional

Array containing the types to be used for casting

Returns
Cake\Database\StatementInterface

insertQuery() ¶ public

insertQuery(string|null $table = null, array $values = [], array<int|string, string> $types = []): Cake\Database\Query\InsertQuery

Create a new InsertQuery instance for this connection.

Parameters
string|null $table optional

The table to insert rows into.

array $values optional

Associative array of column => value to be inserted.

array<int|string, string> $types optional

Associative array containing the types to be used for casting.

Returns
Cake\Database\Query\InsertQuery

isConnected() ¶ public

isConnected(): bool

Returns whether connection to database server was already established.

Returns
bool

isQueryLoggingEnabled() ¶ public

isQueryLoggingEnabled(): bool

Check if query logging is enabled.

Returns
bool

isSavePointsEnabled() ¶ public

isSavePointsEnabled(): bool

Returns whether this connection is using savepoints for nested transactions

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

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(Cake\Database\Query|string $query): Cake\Database\StatementInterface

Prepares a SQL statement to be executed.

Parameters
Cake\Database\Query|string $query

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, Cake\Database\TypeInterface|string|int $type = 'string'): string

Quotes value to be used safely in database query.

This uses PDO::quote() and requires supportsQuoting() to work.

Parameters
mixed $value

The value to quote.

Cake\Database\TypeInterface|string|int $type optional

Type to be used for determining kind of quoting to perform

Returns
string

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.

This does not require supportsQuoting() to work.

Parameters
string $identifier

The identifier to quote.

Returns
string

releaseSavePoint() ¶ public

releaseSavePoint(string|int $name): void

Releases a save point by its name.

Parameters
string|int $name

Save point name or id

Returns
void

role() ¶ public

role(): string

Returns the connection role: read or write.

Returns
string

rollback() ¶ public

rollback(bool|null $toBeginning = null): bool

Rollback current transaction.

Parameters
bool|null $toBeginning optional

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

Returns
bool

rollbackSavepoint() ¶ public

rollbackSavepoint(string|int $name): void

Rollback a save point by its name.

Parameters
string|int $name

Save point name or id

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

selectQuery() ¶ public

selectQuery(Cake\Database\ExpressionInterface|callable|array|string $fields = [], array|string $table = [], array<string, string> $types = []): Cake\Database\Query\SelectQuery

Create a new SelectQuery instance for this connection.

Parameters
Cake\Database\ExpressionInterface|callable|array|string $fields optional

fields to be added to the list.

array|string $table optional

The table or list of tables to query.

array<string, string> $types optional

Associative array containing the types to be used for casting.

Returns
Cake\Database\Query\SelectQuery

setCacher() ¶ public

setCacher(Psr\SimpleCache\CacheInterface $cacher): $this

Set a cacher.

Parameters
Psr\SimpleCache\CacheInterface $cacher
Returns
$this

setDriver() ¶ public

setDriver(Cake\Database\DriverInterface|string $driver, array<string, mixed> $config = []): $this

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

Parameters
Cake\Database\DriverInterface|string $driver

The driver instance to use.

array<string, mixed> $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() ¶ public

setLogger(Psr\Log\LoggerInterface $logger): $this

Sets a logger

Parameters
Psr\Log\LoggerInterface $logger

Logger object

Returns
$this

setSchemaCollection() ¶ public

setSchemaCollection(Cake\Database\Schema\CollectionInterface $collection): $this

Sets a Schema\Collection object for this connection.

Parameters
Cake\Database\Schema\CollectionInterface $collection

The schema collection object

Returns
$this

supportsDynamicConstraints() ¶ public

supportsDynamicConstraints(): bool

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

Returns
bool

supportsQuoting() ¶ public

supportsQuoting(): bool

Checks if using quote() is supported.

This is not required to use quoteIdentifier().

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.

The callback will receive the connection instance as its first argument.

Example:

$connection->transactional(function ($connection) {
  $connection->newQuery()->delete('users')->execute();
});
Parameters
callable $callback
Returns
mixed

update() ¶ public

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

Executes an UPDATE statement on the specified table.

Parameters
string $table

the table to update rows from

array $values

values to be updated

array $conditions optional

conditions to be set for update statement

array<string> $types optional

list of associative array containing the types to be used for casting

Returns
Cake\Database\StatementInterface

updateQuery() ¶ public

updateQuery(Cake\Database\ExpressionInterface|string|null $table = null, array $values = [], array $conditions = [], array<string, string> $types = []): Cake\Database\Query\UpdateQuery

Create a new UpdateQuery instance for this connection.

Parameters
Cake\Database\ExpressionInterface|string|null $table optional

The table to update rows of.

array $values optional

Values to be updated.

array $conditions optional

Conditions to be set for the update statement.

array<string, string> $types optional

Associative array containing the types to be used for casting.

Returns
Cake\Database\Query\UpdateQuery

wasNestedTransactionRolledback() ¶ protected

wasNestedTransactionRolledback(): bool

Returns whether some nested transaction has been already rolled back.

Returns
bool

Property Detail

$_config ¶ protected

Contains the configuration params for this connection.

Type
array<string, mixed>

$_logQueries ¶ protected

Whether to log queries generated during this connection.

Type
bool

$_logger ¶ protected

Logger object instance.

Type
Psr\Log\LoggerInterface|null

$_schemaCollection ¶ protected

The schema collection object

Type
Cake\Database\Schema\CollectionInterface|null

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

$cacher ¶ protected

Cacher object instance.

Type
Psr\SimpleCache\CacheInterface|null

$nestedTransactionRollbackException ¶ protected

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

Type
Cake\Database\Exception\NestedTransactionRollbackException|null

$readDriver ¶ protected

Type
Cake\Database\DriverInterface

$writeDriver ¶ protected

Type
Cake\Database\DriverInterface
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs