---
title: "Phalcon Datamapper"
version: "5.20"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Datamapper
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## DataMapper\Pdo\Connection
Class
Provides array quoting, profiling, a new `perform()` method, new `fetch*()`
methods
- [`Phalcon\DataMapper\Pdo\Connection\AbstractConnection`](#datamapperpdoconnectionabstractconnection)
- **`Phalcon\DataMapper\Pdo\Connection`**
`Phalcon\DataMapper\Pdo\Connection\AbstractConnection` · `Phalcon\DataMapper\Pdo\Exception\DriverNotSupported` · `Phalcon\DataMapper\Pdo\Profiler\Profiler` · `Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface`
### Method Summary
Constructor.
The purpose of this method is to hide sensitive data from stack traces.
Connects to the database.
Disconnects from the database.
### Properties
### Methods
__construct()
```php
public function __construct(
string $dsn,
string|null $username = null,
string|null $password = null,
array $options = [],
array $queries = [],
ProfilerInterface|null $profiler = null
);
```
Constructor.
This overrides the parent so that it can take connection attributes as a
constructor parameter, and set them after connection.
__debugInfo()
```php
public function __debugInfo(): array;
```
The purpose of this method is to hide sensitive data from stack traces.
connect()
```php
public function connect(): void;
```
Connects to the database.
disconnect()
```php
public function disconnect(): void;
```
Disconnects from the database.
## DataMapper\Pdo\ConnectionLocator
Class
Manages Connection instances for default, read, and write connections.
The locator gives its events manager to each connection that it returns,
so connections that are built on demand also fire the DataMapper events.
- **`Phalcon\DataMapper\Pdo\ConnectionLocator`** - implements [`Phalcon\DataMapper\Pdo\ConnectionLocatorInterface`](#datamapperpdoconnectionlocatorinterface), [`Phalcon\Contracts\Events\EventsAware`](/5.20/api/phalcon_contracts/#contractseventseventsaware)
`Phalcon\Contracts\Events\EventsAware` · `Phalcon\DataMapper\Pdo\Connection\ConnectionInterface` · `Phalcon\DataMapper\Pdo\Exception\ConnectionNotFound` · `Phalcon\Events\ManagerInterface` · `Phalcon\Events\Traits\EventsAwareTrait`
### Method Summary
Constructor.
Returns the default connection object.
Returns a read connection by name; if no name is given, picks a
Returns a write connection by name; if no name is given, picks a
Sets the default connection factory.
Sets a read connection factory by name.
Sets a write connection factory by name.
Returns a connection by name.
### Properties
A default Connection connection factory/instance.
A registry of Connection "read" factories/instances.
A registry of Connection "write" factories/instances.
### Methods
__construct()
```php
public function __construct(
ConnectionInterface $master,
array $read = [],
array $write = []
);
```
Constructor.
getMaster()
```php
public function getMaster(): ConnectionInterface;
```
Returns the default connection object.
getRead()
```php
public function getRead( string $name = "" ): ConnectionInterface;
```
Returns a read connection by name; if no name is given, picks a
random connection; if no read connections are present, returns the
default connection.
getWrite()
```php
public function getWrite( string $name = "" ): ConnectionInterface;
```
Returns a write connection by name; if no name is given, picks a
random connection; if no write connections are present, returns the
default connection.
setMaster()
```php
public function setMaster( ConnectionInterface $callableObject ): static;
```
Sets the default connection factory.
setRead()
```php
public function setRead(
string $name,
callable $callableObject
): static;
```
Sets a read connection factory by name.
setWrite()
```php
public function setWrite(
string $name,
callable $callableObject
): static;
```
Sets a write connection factory by name.
getConnection()
```php
protected function getConnection(
string $type,
string $name = ""
): ConnectionInterface;
```
Returns a connection by name.
## DataMapper\Pdo\ConnectionLocatorInterface
Interface
Locates PDO connections for default, read, and write databases.
- **`Phalcon\DataMapper\Pdo\ConnectionLocatorInterface`**
`Phalcon\DataMapper\Pdo\Connection\ConnectionInterface`
### Method Summary
Returns the default connection object.
Returns a read connection by name; if no name is given, picks a
Returns a write connection by name; if no name is given, picks a
Sets the default connection registry entry.
Sets a read connection registry entry by name.
Sets a write connection registry entry by name.
### Methods
getMaster()
```php
public function getMaster(): ConnectionInterface;
```
Returns the default connection object.
getRead()
```php
public function getRead( string $name = "" ): ConnectionInterface;
```
Returns a read connection by name; if no name is given, picks a
random connection; if no read connections are present, returns the
default connection.
getWrite()
```php
public function getWrite( string $name = "" ): ConnectionInterface;
```
Returns a write connection by name; if no name is given, picks a
random connection; if no write connections are present, returns the
default connection.
setMaster()
```php
public function setMaster( ConnectionInterface $callableObject ): ConnectionLocatorInterface;
```
Sets the default connection registry entry.
setRead()
```php
public function setRead(
string $name,
callable $callableObject
): ConnectionLocatorInterface;
```
Sets a read connection registry entry by name.
setWrite()
```php
public function setWrite(
string $name,
callable $callableObject
): ConnectionLocatorInterface;
```
Sets a write connection registry entry by name.
## DataMapper\Pdo\Connection\AbstractConnection
Abstract
Provides array quoting, profiling, a new `perform()` method, new `fetch*()`
methods
Connections fire the lifecycle events in Phalcon\DataMapper\Pdo\Events when
an events manager is set. ConnectionInterface does not declare the events
manager methods; the EventsAware contract is applied here so that existing
implementations of the interface keep working.
- **`Phalcon\DataMapper\Pdo\Connection\AbstractConnection`** - implements [`Phalcon\DataMapper\Pdo\Connection\ConnectionInterface`](#datamapperpdoconnectionconnectioninterface), [`Phalcon\Contracts\Events\EventsAware`](/5.20/api/phalcon_contracts/#contractseventseventsaware)
- [`Phalcon\DataMapper\Pdo\Connection`](#datamapperpdoconnection)
- [`Phalcon\DataMapper\Pdo\Connection\Decorated`](#datamapperpdoconnectiondecorated)
`BadMethodCallException` · `Phalcon\Contracts\Events\EventsAware` · `Phalcon\DataMapper\Pdo\Events` · `Phalcon\DataMapper\Pdo\Exception\OperationCancelled` · `Phalcon\DataMapper\Pdo\Exception\UnknownDriverMethod` · `Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface` · `Phalcon\Events\ManagerInterface` · `Phalcon\Events\Traits\EventsAwareTrait`
### Method Summary
Proxies to PDO methods created for specific drivers; in particular,
Begins a transaction. If the profiler is enabled, the operation will
Commits the existing transaction. If the profiler is enabled, the
Connects to the database.
Disconnects from the database.
Ensures the connection is alive, reconnecting in place if it is not.
Gets the most recent error code.
Gets the most recent error info.
Executes an SQL statement and returns the number of affected rows. If
Performs a statement and returns the number of affected rows.
Fetches a sequential array of rows from the database; the rows are
Fetches an associative array of rows from the database; the rows are
Fetches a column of rows as a sequential array (default first one).
Fetches multiple from the database as an associative array. The first
Fetches one row from the database as an object where the column values
Fetches a sequential array of rows from the database; the rows are
Fetches one row from the database as an associative array.
Fetches an associative array of rows as key-value pairs (first column is
Fetches the very first value (i.e., first column of the first row).
Return the inner PDO (if any)
Retrieve a database connection attribute
Returns whether transparent auto-reconnect is enabled.
Return an array of available PDO drivers (empty array if none available)
Return the driver name
Returns the Profiler instance.
Gets the quote parameters based on the driver
Is a transaction currently active? If the profiler is enabled, the
Is the PDO connection active?
Returns the last inserted autoincrement sequence value. If the profiler
Performs a query with bound values and returns the resulting
Checks whether the underlying connection is still alive by issuing a
Prepares an SQL statement for execution.
Queries the database and returns a PDOStatement. If the profiler is
Quotes a value for use in an SQL statement. This differs from
Rolls back the current transaction, and restores autocommit mode. If the
Set a database connection attribute
Enables or disables transparent auto-reconnect on a lost connection.
Sets the Profiler instance.
Helper method to get data from PDO based on the method passed
Fires a cancellable "before" event. A listener cancels by stopping the
Recognizes a lost ("gone away") connection. Detection is driver-agnostic:
Bind a value using the proper PDO::PARAM_* type.
### Properties
Whether to transparently reconnect and retry once when a statement fails
because the connection was lost. Opt-in; off by default.
Current transaction nesting level. Tracked locally rather than via
PDO::inTransaction() because some drivers report a broken connection as
being "in transaction".
### Methods
__call()
```php
public function __call(
mixed $name,
array $arguments
);
```
Proxies to PDO methods created for specific drivers; in particular,
`sqlite` and `pgsql`.
beginTransaction()
```php
public function beginTransaction(): bool;
```
Begins a transaction. If the profiler is enabled, the operation will
be recorded.
commit()
```php
public function commit(): bool;
```
Commits the existing transaction. If the profiler is enabled, the
operation will be recorded.
connect()
```php
abstract public function connect(): void;
```
Connects to the database.
disconnect()
```php
abstract public function disconnect(): void;
```
Disconnects from the database.
ensureConnection()
```php
public function ensureConnection(): void;
```
Ensures the connection is alive, reconnecting in place if it is not.
disconnect() is required first because connect() is idempotent and will
not rebuild a dead-but-present handle.
errorCode()
```php
public function errorCode(): string|null;
```
Gets the most recent error code.
errorInfo()
```php
public function errorInfo(): array;
```
Gets the most recent error info.
exec()
```php
public function exec( string $statement ): int;
```
Executes an SQL statement and returns the number of affected rows. If
the profiler is enabled, the operation will be recorded.
fetchAffected()
```php
public function fetchAffected(
string $statement,
array $values = []
): int;
```
Performs a statement and returns the number of affected rows.
fetchAll()
```php
public function fetchAll(
string $statement,
array $values = []
): array;
```
Fetches a sequential array of rows from the database; the rows are
returned as associative arrays.
fetchAssoc()
```php
public function fetchAssoc(
string $statement,
array $values = []
): array;
```
Fetches an associative array of rows from the database; the rows are
returned as associative arrays, and the array of rows is keyed on the
first column of each row.
If multiple rows have the same first column value, the last row with
that value will overwrite earlier rows. This method is more resource
intensive and should be avoided if possible.
fetchColumn()
```php
public function fetchColumn(
string $statement,
array $values = [],
int $column = 0
): array;
```
Fetches a column of rows as a sequential array (default first one).
fetchGroup()
```php
public function fetchGroup(
string $statement,
array $values = [],
int $flags = \PDO::FETCH_ASSOC
): array;
```
Fetches multiple from the database as an associative array. The first
column will be the index key. The default flags are
PDO::FETCH_ASSOC | PDO::FETCH_GROUP
fetchObject()
```php
public function fetchObject(
string $statement,
array $values = [],
string $className = "stdClass",
array $arguments = []
): object;
```
Fetches one row from the database as an object where the column values
are mapped to object properties.
Since PDO injects property values before invoking the constructor, any
initializations for defaults that you potentially have in your object's
constructor, will override the values that have been injected by
`fetchObject`. The default object returned is `\stdClass`
fetchObjects()
```php
public function fetchObjects(
string $statement,
array $values = [],
string $className = "stdClass",
array $arguments = []
): array;
```
Fetches a sequential array of rows from the database; the rows are
returned as objects where the column values are mapped to object
properties.
Since PDO injects property values before invoking the constructor, any
initializations for defaults that you potentially have in your object's
constructor, will override the values that have been injected by
`fetchObject`. The default object returned is `\stdClass`
fetchOne()
```php
public function fetchOne(
string $statement,
array $values = []
): array;
```
Fetches one row from the database as an associative array.
fetchPairs()
```php
public function fetchPairs(
string $statement,
array $values = []
): array;
```
Fetches an associative array of rows as key-value pairs (first column is
the key, second column is the value).
fetchValue()
```php
public function fetchValue(
string $statement,
array $values = []
);
```
Fetches the very first value (i.e., first column of the first row).
getAdapter()
```php
public function getAdapter(): \PDO;
```
Return the inner PDO (if any)
getAttribute()
```php
public function getAttribute( int $attribute ): mixed;
```
Retrieve a database connection attribute
getAutoReconnect()
```php
public function getAutoReconnect(): bool;
```
Returns whether transparent auto-reconnect is enabled.
getAvailableDrivers()
```php
public static function getAvailableDrivers(): array;
```
Return an array of available PDO drivers (empty array if none available)
getDriverName()
```php
public function getDriverName(): string;
```
Return the driver name
getProfiler()
```php
public function getProfiler(): ProfilerInterface;
```
Returns the Profiler instance.
getQuoteNames()
```php
public function getQuoteNames( string $driver = "" ): array;
```
Gets the quote parameters based on the driver
inTransaction()
```php
public function inTransaction(): bool;
```
Is a transaction currently active? If the profiler is enabled, the
operation will be recorded. If the profiler is enabled, the operation
will be recorded.
isConnected()
```php
public function isConnected(): bool;
```
Is the PDO connection active?
lastInsertId()
```php
public function lastInsertId( string|null $name = null ): string;
```
Returns the last inserted autoincrement sequence value. If the profiler
is enabled, the operation will be recorded.
```php
public function perform(
string $statement,
array $values = []
): \PDOStatement;
```
Performs a query with bound values and returns the resulting
PDOStatement; array values will be passed through `quote()` and their
respective placeholders will be replaced in the query string. If the
profiler is enabled, the operation will be recorded.
ping()
```php
public function ping(): bool;
```
Checks whether the underlying connection is still alive by issuing a
trivial query. Returns false if there is no handle or the probe fails.
prepare()
```php
public function prepare(
string $statement,
array $options = []
): \PDOStatement|bool;
```
Prepares an SQL statement for execution.
query()
```php
public function query( string $statement ): \PDOStatement|bool;
```
Queries the database and returns a PDOStatement. If the profiler is
enabled, the operation will be recorded.
quote()
```php
public function quote(
mixed $value,
int $type = \PDO::PARAM_STR
): string;
```
Quotes a value for use in an SQL statement. This differs from
`PDO::quote()` in that it will convert an array into a string of
comma-separated quoted values. The default type is `PDO::PARAM_STR`
rollBack()
```php
public function rollBack(): bool;
```
Rolls back the current transaction, and restores autocommit mode. If the
profiler is enabled, the operation will be recorded.
setAttribute()
```php
public function setAttribute(
int $attribute,
mixed $value
): bool;
```
Set a database connection attribute
setAutoReconnect()
```php
public function setAutoReconnect( bool $autoReconnect ): static;
```
Enables or disables transparent auto-reconnect on a lost connection.
setProfiler()
```php
public function setProfiler( ProfilerInterface $profiler ): static;
```
Sets the Profiler instance.
fetchData()
```php
protected function fetchData(
string $method,
array $arguments,
string $statement,
array $values = []
): array;
```
Helper method to get data from PDO based on the method passed
fireBefore()
```php
protected function fireBefore(
string $eventName,
mixed $data = null
): void;
```
Fires a cancellable "before" event. A listener cancels by stopping the
event and returning false; see Phalcon\DataMapper\Pdo\Events for the
required idiom. The operation does not run when it is cancelled.
isConnectionError()
```php
protected function isConnectionError( \Throwable $exception ): bool;
```
Recognizes a lost ("gone away") connection. Detection is driver-agnostic:
the driver name is not queried because the underlying connection may be
dead by this point. The MySQL error codes and PostgreSQL SQLSTATEs do not
overlap, so all known signatures are checked unconditionally.
```php
protected function performBind(
\PDOStatement $statement,
mixed $name,
mixed $arguments
): void;
```
Bind a value using the proper PDO::PARAM_* type.
## DataMapper\Pdo\Connection\ConnectionInterface
Interface
Provides array quoting, profiling, a new `perform()` method, new `fetch*()`
methods
- [`Phalcon\DataMapper\Pdo\Connection\PdoInterface`](#datamapperpdoconnectionpdointerface)
- **`Phalcon\DataMapper\Pdo\Connection\ConnectionInterface`**
`Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface`
### Method Summary
Connects to the database.
Disconnects from the database.
Performs a statement and returns the number of affected rows.
Fetches a sequential array of rows from the database; the rows are
Fetches an associative array of rows from the database; the rows are
Fetches a column of rows as a sequential array (default first one).
Fetches multiple from the database as an associative array. The first
Fetches one row from the database as an object where the column values
Fetches a sequential array of rows from the database; the rows are
Fetches one row from the database as an associative array.
Fetches an associative array of rows as key-value pairs (first column is
Fetches the very first value (i.e., first column of the first row).
Return the inner PDO (if any)
Returns the Profiler instance.
Is the PDO connection active?
Performs a query with bound values and returns the resulting
Sets the Profiler instance.
### Methods
connect()
```php
public function connect(): void;
```
Connects to the database.
disconnect()
```php
public function disconnect(): void;
```
Disconnects from the database.
fetchAffected()
```php
public function fetchAffected(
string $statement,
array $values = []
): int;
```
Performs a statement and returns the number of affected rows.
fetchAll()
```php
public function fetchAll(
string $statement,
array $values = []
): array;
```
Fetches a sequential array of rows from the database; the rows are
returned as associative arrays.
fetchAssoc()
```php
public function fetchAssoc(
string $statement,
array $values = []
): array;
```
Fetches an associative array of rows from the database; the rows are
returned as associative arrays, and the array of rows is keyed on the
first column of each row.
If multiple rows have the same first column value, the last row with
that value will overwrite earlier rows. This method is more resource
intensive and should be avoided if possible.
fetchColumn()
```php
public function fetchColumn(
string $statement,
array $values = [],
int $column = 0
): array;
```
Fetches a column of rows as a sequential array (default first one).
fetchGroup()
```php
public function fetchGroup(
string $statement,
array $values = [],
int $flags = \PDO::FETCH_ASSOC
): array;
```
Fetches multiple from the database as an associative array. The first
column will be the index key. The default flags are
PDO::FETCH_ASSOC | PDO::FETCH_GROUP
fetchObject()
```php
public function fetchObject(
string $statement,
array $values = [],
string $className = "stdClass",
array $arguments = []
): object;
```
Fetches one row from the database as an object where the column values
are mapped to object properties.
Since PDO injects property values before invoking the constructor, any
initializations for defaults that you potentially have in your object's
constructor, will override the values that have been injected by
`fetchObject`. The default object returned is `\stdClass`
fetchObjects()
```php
public function fetchObjects(
string $statement,
array $values = [],
string $className = "stdClass",
array $arguments = []
): array;
```
Fetches a sequential array of rows from the database; the rows are
returned as objects where the column values are mapped to object
properties.
Since PDO injects property values before invoking the constructor, any
initializations for defaults that you potentially have in your object's
constructor, will override the values that have been injected by
`fetchObject`. The default object returned is `\stdClass`
fetchOne()
```php
public function fetchOne(
string $statement,
array $values = []
): array;
```
Fetches one row from the database as an associative array.
fetchPairs()
```php
public function fetchPairs(
string $statement,
array $values = []
): array;
```
Fetches an associative array of rows as key-value pairs (first column is
the key, second column is the value).
fetchValue()
```php
public function fetchValue(
string $statement,
array $values = []
): mixed;
```
Fetches the very first value (i.e., first column of the first row).
getAdapter()
```php
public function getAdapter(): \PDO;
```
Return the inner PDO (if any)
getProfiler()
```php
public function getProfiler(): ProfilerInterface;
```
Returns the Profiler instance.
isConnected()
```php
public function isConnected(): bool;
```
Is the PDO connection active?
```php
public function perform(
string $statement,
array $values = []
): \PDOStatement;
```
Performs a query with bound values and returns the resulting
PDOStatement; array values will be passed through `quote()` and their
respective placeholders will be replaced in the query string. If the
profiler is enabled, the operation will be recorded.
setProfiler()
```php
public function setProfiler( ProfilerInterface $profiler );
```
Sets the Profiler instance.
## DataMapper\Pdo\Connection\Decorated
Class
Decorates an existing PDO instance with the extended methods.
- [`Phalcon\DataMapper\Pdo\Connection\AbstractConnection`](#datamapperpdoconnectionabstractconnection)
- **`Phalcon\DataMapper\Pdo\Connection\Decorated`**
`Phalcon\DataMapper\Pdo\Exception\CannotDisconnect` · `Phalcon\DataMapper\Pdo\Profiler\Profiler` · `Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface`
### Method Summary
Constructor.
Connects to the database.
Disconnects from the database; disallowed with decorated PDO connections.
### Methods
__construct()
```php
public function __construct(
\PDO $pdo,
ProfilerInterface|null $profiler = null
);
```
Constructor.
This overrides the parent so that it can take an existing PDO instance
and decorate it with the extended methods.
connect()
```php
public function connect(): void;
```
Connects to the database.
disconnect()
```php
public function disconnect(): void;
```
Disconnects from the database; disallowed with decorated PDO connections.
## DataMapper\Pdo\Connection\PdoInterface
Interface
An interface to the native PDO object.
- **`Phalcon\DataMapper\Pdo\Connection\PdoInterface`**
- [`Phalcon\DataMapper\Pdo\Connection\ConnectionInterface`](#datamapperpdoconnectionconnectioninterface)
### Method Summary
Begins a transaction. If the profiler is enabled, the operation will
Commits the existing transaction. If the profiler is enabled, the
Gets the most recent error code.
Gets the most recent error info.
Executes an SQL statement and returns the number of affected rows. If
Retrieve a database connection attribute
Return an array of available PDO drivers (empty array if none available)
Is a transaction currently active? If the profiler is enabled, the
Returns the last inserted autoincrement sequence value. If the profiler
Prepares an SQL statement for execution.
Queries the database and returns a PDOStatement. If the profiler is
Quotes a value for use in an SQL statement. This differs from
Rolls back the current transaction, and restores autocommit mode. If the
Set a database connection attribute
### Methods
beginTransaction()
```php
public function beginTransaction(): bool;
```
Begins a transaction. If the profiler is enabled, the operation will
be recorded.
commit()
```php
public function commit(): bool;
```
Commits the existing transaction. If the profiler is enabled, the
operation will be recorded.
errorCode()
```php
public function errorCode(): null|string;
```
Gets the most recent error code.
errorInfo()
```php
public function errorInfo(): array;
```
Gets the most recent error info.
exec()
```php
public function exec( string $statement ): int;
```
Executes an SQL statement and returns the number of affected rows. If
the profiler is enabled, the operation will be recorded.
getAttribute()
```php
public function getAttribute( int $attribute ): mixed;
```
Retrieve a database connection attribute
getAvailableDrivers()
```php
public static function getAvailableDrivers(): array;
```
Return an array of available PDO drivers (empty array if none available)
inTransaction()
```php
public function inTransaction(): bool;
```
Is a transaction currently active? If the profiler is enabled, the
operation will be recorded. If the profiler is enabled, the operation
will be recorded.
lastInsertId()
```php
public function lastInsertId( string|null $name = null ): string;
```
Returns the last inserted autoincrement sequence value. If the profiler
is enabled, the operation will be recorded.
prepare()
```php
public function prepare(
string $statement,
array $options = []
): \PDOStatement|bool;
```
Prepares an SQL statement for execution.
query()
```php
public function query( string $statement ): \PDOStatement|bool;
```
Queries the database and returns a PDOStatement. If the profiler is
enabled, the operation will be recorded.
quote()
```php
public function quote(
mixed $value,
int $type = \PDO::PARAM_STR
): string;
```
Quotes a value for use in an SQL statement. This differs from
`PDO::quote()` in that it will convert an array into a string of
comma-separated quoted values. The default type is `PDO::PARAM_STR`
rollBack()
```php
public function rollBack(): bool;
```
Rolls back the current transaction, and restores autocommit mode. If the
profiler is enabled, the operation will be recorded.
setAttribute()
```php
public function setAttribute(
int $attribute,
mixed $value
): bool;
```
Set a database connection attribute
## DataMapper\Pdo\Events
Class
Lifecycle event names fired by the DataMapper connections through
Phalcon\Events\Manager. One public constant per event.
The `before*` events are cancellable. To cancel an operation, a listener
must stop the event and return false:
$manager->attach(
Events::BEFORE_PERFORM,
function ($event) \{
$event->stop();
return false;
\}
);
Both parts are necessary. `stop()` alone abandons the queue but returns
the listener's own value, which the connection cannot tell apart from
"no listeners". `return false` alone is replaced by any later non-null
return while the manager's stopOnFalse mode is off, which is the default.
A cancelled operation throws
Phalcon\DataMapper\Pdo\Exception\OperationCancelled.
The `after*` events are not cancellable. The operation is complete when
they fire.
There are two groups of events. The operation events - perform, exec,
query and the three transaction events - belong to one operation each.
`prepare()` has no operation events because `perform()` calls it, and
nested events for one logical operation give listeners two counts of the
same work. The connection events - connect, disconnect and connectionLost
- report a change of the connection state. They fire each time the state
changes, whichever method causes it. An automatic reconnect from any
method therefore reports the lost connection and the new one.
- **`Phalcon\DataMapper\Pdo\Events`**
### Constants
## DataMapper\Pdo\Exception\CannotDisconnect
Class
ExtendedPdo could not disconnect; e.g., because its PDO connection was
created externally and then injected.
- `\Exception`
- [`Phalcon\DataMapper\Pdo\Exception\Exception`](#datamapperpdoexceptionexception)
- **`Phalcon\DataMapper\Pdo\Exception\CannotDisconnect`**
## DataMapper\Pdo\Exception\ConnectionNotFound
Class
Locator could not find a named connection.
- `\Exception`
- [`Phalcon\DataMapper\Pdo\Exception\Exception`](#datamapperpdoexceptionexception)
- **`Phalcon\DataMapper\Pdo\Exception\ConnectionNotFound`**
## DataMapper\Pdo\Exception\DriverNotSupported
Class
- `\InvalidArgumentException`
- **`Phalcon\DataMapper\Pdo\Exception\DriverNotSupported`**
`InvalidArgumentException`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $driver );
```
## DataMapper\Pdo\Exception\Exception
Class
Base Exception class
- `\Exception`
- **`Phalcon\DataMapper\Pdo\Exception\Exception`**
- [`Phalcon\DataMapper\Pdo\Exception\CannotDisconnect`](#datamapperpdoexceptioncannotdisconnect)
- [`Phalcon\DataMapper\Pdo\Exception\ConnectionNotFound`](#datamapperpdoexceptionconnectionnotfound)
- [`Phalcon\DataMapper\Pdo\Exception\OperationCancelled`](#datamapperpdoexceptionoperationcancelled)
## DataMapper\Pdo\Exception\OperationCancelled
Class
A listener cancelled a cancellable "before" event, so the operation did
not run. This is a deliberate cancellation, not a database failure. Catch
this class to tell the two apart.
- `\Exception`
- [`Phalcon\DataMapper\Pdo\Exception\Exception`](#datamapperpdoexceptionexception)
- **`Phalcon\DataMapper\Pdo\Exception\OperationCancelled`**
### Method Summary
### Methods
__construct()
```php
public function __construct( string $eventName );
```
## DataMapper\Pdo\Exception\UnknownDriverMethod
Class
- `\BadMethodCallException`
- **`Phalcon\DataMapper\Pdo\Exception\UnknownDriverMethod`**
`BadMethodCallException`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $message );
```
## DataMapper\Pdo\Exception\UnknownQueryMethod
Class
- `\BadMethodCallException`
- **`Phalcon\DataMapper\Pdo\Exception\UnknownQueryMethod`**
`BadMethodCallException`
### Method Summary
### Methods
__construct()
```php
public function __construct( string $method );
```
## DataMapper\Pdo\Profiler\MemoryLogger
Class
A memory-based logger.
- **`Phalcon\DataMapper\Pdo\Profiler\MemoryLogger`** - implements [`Phalcon\Logger\LoggerInterface`](/5.20/api/phalcon_logger/#loggerloggerinterface)
`Phalcon\Logger\Adapter\AdapterInterface` · `Phalcon\Logger\Adapter\Noop` · `Phalcon\Logger\Enum` · `Phalcon\Logger\LoggerInterface`
### Method Summary
Returns an adapter from the stack
Returns the adapter stack array
Returns the log level
Returns the logged messages.
Returns the name of the logger
Logs a message.
### Properties
### Methods
alert()
```php
public function alert(
string $message,
array $context = []
): void;
```
critical()
```php
public function critical(
string $message,
array $context = []
): void;
```
debug()
```php
public function debug(
string $message,
array $context = []
): void;
```
emergency()
```php
public function emergency(
string $message,
array $context = []
): void;
```
error()
```php
public function error(
string $message,
array $context = []
): void;
```
getAdapter()
```php
public function getAdapter( string $name ): AdapterInterface;
```
Returns an adapter from the stack
getAdapters()
```php
public function getAdapters(): array;
```
Returns the adapter stack array
getLogLevel()
```php
public function getLogLevel(): int;
```
Returns the log level
getMessages()
```php
public function getMessages(): array;
```
Returns the logged messages.
getName()
```php
public function getName(): string;
```
Returns the name of the logger
info()
```php
public function info(
string $message,
array $context = []
): void;
```
log()
```php
public function log(
mixed $level,
string $message,
array $context = []
): void;
```
Logs a message.
notice()
```php
public function notice(
string $message,
array $context = []
): void;
```
trace()
```php
public function trace(
string $message,
array $context = []
): void;
```
warning()
```php
public function warning(
string $message,
array $context = []
): void;
```
## DataMapper\Pdo\Profiler\Profiler
Class
Sends query profiles to a logger.
- **`Phalcon\DataMapper\Pdo\Profiler\Profiler`** - implements [`Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface`](#datamapperpdoprofilerprofilerinterface)
`Phalcon\DataMapper\Pdo\Exception\Exception` · `Phalcon\Logger\Enum` · `Phalcon\Logger\LoggerInterface` · `Phalcon\Support\Helper\Json\Encode`
### Method Summary
Constructor.
Finishes and logs a profile entry.
Returns the log message format string, with placeholders.
Returns the level at which to log profile messages.
Returns the underlying logger instance.
Returns true if logging is active.
Enable or disable profiler logging.
Sets the log message format string, with placeholders.
Level at which to log profile messages.
Starts a profile entry.
### Properties
### Methods
__construct()
```php
public function __construct( LoggerInterface|null $logger = null );
```
Constructor.
finish()
```php
public function finish(
string|null $statement = null,
array $values = []
): void;
```
Finishes and logs a profile entry.
```php
public function getLogFormat(): string;
```
Returns the log message format string, with placeholders.
getLogLevel()
```php
public function getLogLevel(): string;
```
Returns the level at which to log profile messages.
getLogger()
```php
public function getLogger(): LoggerInterface;
```
Returns the underlying logger instance.
isActive()
```php
public function isActive(): bool;
```
Returns true if logging is active.
setActive()
```php
public function setActive( bool $active ): ProfilerInterface;
```
Enable or disable profiler logging.
```php
public function setLogFormat( string $logFormat ): ProfilerInterface;
```
Sets the log message format string, with placeholders.
setLogLevel()
```php
public function setLogLevel( string $logLevel ): ProfilerInterface;
```
Level at which to log profile messages.
start()
```php
public function start( string $method ): void;
```
Starts a profile entry.
## DataMapper\Pdo\Profiler\ProfilerInterface
Interface
Interface to send query profiles to a logger.
- **`Phalcon\DataMapper\Pdo\Profiler\ProfilerInterface`**
`Phalcon\Logger\LoggerInterface`
### Method Summary
Finishes and logs a profile entry.
Returns the log message format string, with placeholders.
Returns the level at which to log profile messages.
Returns the underlying logger instance.
Returns true if logging is active.
Enable or disable profiler logging.
Sets the log message format string, with placeholders.
Level at which to log profile messages.
Starts a profile entry.
### Methods
finish()
```php
public function finish(
string|null $statement = null,
array $values = []
): void;
```
Finishes and logs a profile entry.
```php
public function getLogFormat(): string;
```
Returns the log message format string, with placeholders.
getLogLevel()
```php
public function getLogLevel(): string;
```
Returns the level at which to log profile messages.
getLogger()
```php
public function getLogger(): LoggerInterface;
```
Returns the underlying logger instance.
isActive()
```php
public function isActive(): bool;
```
Returns true if logging is active.
setActive()
```php
public function setActive( bool $active ): ProfilerInterface;
```
Enable or disable profiler logging.
```php
public function setLogFormat( string $logFormat ): ProfilerInterface;
```
Sets the log message format string, with placeholders.
setLogLevel()
```php
public function setLogLevel( string $logLevel ): ProfilerInterface;
```
Level at which to log profile messages.
start()
```php
public function start( string $method ): void;
```
Starts a profile entry.
## DataMapper\Query\AbstractConditions
Abstract
Class AbstractConditions
- [`Phalcon\DataMapper\Query\AbstractQuery`](#datamapperqueryabstractquery)
- **`Phalcon\DataMapper\Query\AbstractConditions`**
- [`Phalcon\DataMapper\Query\Delete`](#datamapperquerydelete)
- [`Phalcon\DataMapper\Query\Select`](#datamapperqueryselect)
- [`Phalcon\DataMapper\Query\Update`](#datamapperqueryupdate)
### Method Summary
Sets a `AND` for a `WHERE` condition
Concatenates to the most recent `WHERE` clause
Sets the `LIMIT` clause
Sets the `OFFSET` clause
Sets a `OR` for a `WHERE` condition
Sets the `ORDER BY`
Sets a `WHERE` condition
Appends a conditional
Concatenates a conditional
Builds a `BY` list
Builds the conditional string
Builds the `LIMIT` clause
Builds the `LIMIT` clause for all drivers
Builds the early `LIMIT` clause - MS SQLServer
Builds the `LIMIT` clause for MSSQLServer
Processes a value (array or string) and merges it with the store
### Methods
andWhere()
```php
public function andWhere(
string $condition,
mixed $value = null,
int $type = -1
): AbstractConditions;
```
Sets a `AND` for a `WHERE` condition
appendWhere()
```php
public function appendWhere(
string $condition,
mixed $value = null,
int $type = -1
): AbstractConditions;
```
Concatenates to the most recent `WHERE` clause
limit()
```php
public function limit( int $limit ): AbstractConditions;
```
Sets the `LIMIT` clause
offset()
```php
public function offset( int $offset ): AbstractConditions;
```
Sets the `OFFSET` clause
orWhere()
```php
public function orWhere(
string $condition,
mixed $value = null,
int $type = -1
): AbstractConditions;
```
Sets a `OR` for a `WHERE` condition
orderBy()
```php
public function orderBy( mixed $orderBy ): AbstractConditions;
```
Sets the `ORDER BY`
where()
```php
public function where(
string $condition,
mixed $value = null,
int $type = -1
): AbstractConditions;
```
Sets a `WHERE` condition
whereEquals()
```php
public function whereEquals( array $columnsValues ): AbstractConditions;
```
addCondition()
```php
protected function addCondition(
string $store,
string $andor,
string $condition,
mixed $value = null,
int $type = -1
): void;
```
Appends a conditional
appendCondition()
```php
protected function appendCondition(
string $store,
string $condition,
mixed $value = null,
int $type = -1
): void;
```
Concatenates a conditional
buildBy()
```php
protected function buildBy( string $type ): string;
```
Builds a `BY` list
buildCondition()
```php
protected function buildCondition( string $type ): string;
```
Builds the conditional string
buildLimit()
```php
protected function buildLimit(): string;
```
Builds the `LIMIT` clause
buildLimitCommon()
```php
protected function buildLimitCommon(): string;
```
Builds the `LIMIT` clause for all drivers
buildLimitEarly()
```php
protected function buildLimitEarly(): string;
```
Builds the early `LIMIT` clause - MS SQLServer
buildLimitSqlsrv()
```php
protected function buildLimitSqlsrv(): string;
```
Builds the `LIMIT` clause for MSSQLServer
processValue()
```php
protected function processValue(
string $store,
mixed $data
): void;
```
Processes a value (array or string) and merges it with the store
## DataMapper\Query\AbstractQuery
Abstract
Class AbstractQuery
- **`Phalcon\DataMapper\Query\AbstractQuery`**
- [`Phalcon\DataMapper\Query\AbstractConditions`](#datamapperqueryabstractconditions)
- [`Phalcon\DataMapper\Query\Insert`](#datamapperqueryinsert)
`Phalcon\DataMapper\Pdo\Connection`
### Method Summary
AbstractQuery constructor.
Binds a value inline
Binds a value - auto-detects the type if necessary
Binds an array of values
Returns all the bound values
Return the generated statement
Performs a statement in the connection
Quotes the identifier
Resets the internal array
Resets the columns
Resets the flags
Resets the from
Resets the group by
Resets the having
Resets the limit and offset
Resets the order by
Resets the where
Sets a flag for the query such as "DISTINCT"
Builds the flags statement(s)
Builds the `RETURNING` clause
Indents a collection
### Properties
### Methods
__construct()
```php
public function __construct(
Connection $connection,
Bind $bind
);
```
AbstractQuery constructor.
bindInline()
```php
public function bindInline(
mixed $value,
int $type = -1
): string;
```
Binds a value inline
bindValue()
```php
public function bindValue(
string $key,
mixed $value,
int $type = -1
): AbstractQuery;
```
Binds a value - auto-detects the type if necessary
bindValues()
```php
public function bindValues( array $values ): AbstractQuery;
```
Binds an array of values
getBindValues()
```php
public function getBindValues(): array;
```
Returns all the bound values
getStatement()
```php
abstract public function getStatement(): string;
```
Return the generated statement
```php
public function perform();
```
Performs a statement in the connection
quoteIdentifier()
```php
public function quoteIdentifier(
string $name,
int $type = \PDO::PARAM_STR
): string;
```
Quotes the identifier
reset()
```php
public function reset(): void;
```
Resets the internal array
resetColumns()
```php
public function resetColumns(): void;
```
Resets the columns
resetFlags()
```php
public function resetFlags(): void;
```
Resets the flags
resetFrom()
```php
public function resetFrom(): void;
```
Resets the from
resetGroupBy()
```php
public function resetGroupBy(): void;
```
Resets the group by
resetHaving()
```php
public function resetHaving(): void;
```
Resets the having
resetLimit()
```php
public function resetLimit(): void;
```
Resets the limit and offset
resetOrderBy()
```php
public function resetOrderBy(): void;
```
Resets the order by
resetWhere()
```php
public function resetWhere(): void;
```
Resets the where
setFlag()
```php
public function setFlag(
string $flag,
bool $enable = true
): void;
```
Sets a flag for the query such as "DISTINCT"
buildFlags()
```php
protected function buildFlags();
```
Builds the flags statement(s)
buildReturning()
```php
protected function buildReturning(): string;
```
Builds the `RETURNING` clause
indent()
```php
protected function indent(
array $collection,
string $glue = ""
): string;
```
Indents a collection
## DataMapper\Query\Bind
Class
Class Bind
- **`Phalcon\DataMapper\Query\Bind`**
### Method Summary
Removes a value from the store
Sets a value
Sets values from an array
Returns the internal collection
Auto detects the PDO type
Processes an array - if passed as an `inline` parameter
### Properties
### Methods
bindInline()
```php
public function bindInline(
mixed $value,
int $type = -1
): string;
```
remove()
```php
public function remove( string $key ): void;
```
Removes a value from the store
setValue()
```php
public function setValue(
string $key,
mixed $value,
int $type = -1
): void;
```
Sets a value
setValues()
```php
public function setValues(
array $values,
int $type = -1
): void;
```
Sets values from an array
toArray()
```php
public function toArray(): array;
```
Returns the internal collection
getType()
```php
protected function getType( mixed $value ): int;
```
Auto detects the PDO type
inlineArray()
```php
protected function inlineArray(
array $data,
int $type
): string;
```
Processes an array - if passed as an `inline` parameter
## DataMapper\Query\Delete
Class
Delete Query
- [`Phalcon\DataMapper\Query\AbstractQuery`](#datamapperqueryabstractquery)
- [`Phalcon\DataMapper\Query\AbstractConditions`](#datamapperqueryabstractconditions)
- **`Phalcon\DataMapper\Query\Delete`**
`Phalcon\DataMapper\Pdo\Connection`
### Method Summary
Delete constructor.
Adds table(s) in the query
Resets the internal store
Adds the `RETURNING` clause
### Methods
__construct()
```php
public function __construct(
Connection $connection,
Bind $bind
);
```
Delete constructor.
from()
```php
public function from( string $table ): Delete;
```
Adds table(s) in the query
getStatement()
```php
public function getStatement(): string;
```
reset()
```php
public function reset(): void;
```
Resets the internal store
returning()
```php
public function returning( array $columns ): Delete;
```
Adds the `RETURNING` clause
## DataMapper\Query\Insert
Class
Insert Query
- [`Phalcon\DataMapper\Query\AbstractQuery`](#datamapperqueryabstractquery)
- **`Phalcon\DataMapper\Query\Insert`**
`Phalcon\DataMapper\Pdo\Connection`
### Method Summary
Insert constructor.
Sets a column for the `INSERT` query
Mass sets columns and values for the `INSERT`
Returns the id of the last inserted record
Adds table(s) in the query
Resets the internal store
Adds the `RETURNING` clause
Sets a column = value condition
### Methods
__construct()
```php
public function __construct(
Connection $connection,
Bind $bind
);
```
Insert constructor.
column()
```php
public function column(
string $column,
mixed $value = null,
int $type = -1
): Insert;
```
Sets a column for the `INSERT` query
columns()
```php
public function columns( array $columns ): Insert;
```
Mass sets columns and values for the `INSERT`
getLastInsertId()
```php
public function getLastInsertId( string|null $name = null ): string;
```
Returns the id of the last inserted record
getStatement()
```php
public function getStatement(): string;
```
into()
```php
public function into( string $table ): Insert;
```
Adds table(s) in the query
reset()
```php
public function reset(): void;
```
Resets the internal store
returning()
```php
public function returning( array $columns ): Insert;
```
Adds the `RETURNING` clause
set()
```php
public function set(
string $column,
mixed $value = null
): Insert;
```
Sets a column = value condition
## DataMapper\Query\QueryFactory
Class
QueryFactory
- **`Phalcon\DataMapper\Query\QueryFactory`**
`Phalcon\DataMapper\Pdo\Connection`
### Method Summary
QueryFactory constructor.
Create a new Bind object
Create a new Delete object
Create a new Insert object
Create a new Select object
Create a new Update object
### Properties
### Methods
__construct()
```php
public function __construct( string $selectClass = "" );
```
QueryFactory constructor.
newBind()
```php
public function newBind(): Bind;
```
Create a new Bind object
newDelete()
```php
public function newDelete( Connection $connection ): Delete;
```
Create a new Delete object
newInsert()
```php
public function newInsert( Connection $connection ): Insert;
```
Create a new Insert object
newSelect()
```php
public function newSelect( Connection $connection ): Select;
```
Create a new Select object
newUpdate()
```php
public function newUpdate( Connection $connection ): Update;
```
Create a new Update object
## DataMapper\Query\Select
Class
Select Query
- [`Phalcon\DataMapper\Query\AbstractQuery`](#datamapperqueryabstractquery)
- [`Phalcon\DataMapper\Query\AbstractConditions`](#datamapperqueryabstractconditions)
- **`Phalcon\DataMapper\Query\Select`**
`BadMethodCallException` · `Phalcon\DataMapper\Pdo\Exception\UnknownQueryMethod`
### Method Summary
Proxied methods to the connection
Sets a `AND` for a `HAVING` condition
Concatenates to the most recent `HAVING` clause
Concatenates to the most recent `JOIN` clause
The `AS` statement for the query - useful in sub-queries
The columns to select from. If a key is set in the array element, the
Enable the `FOR UPDATE` for the query
Adds table(s) in the query
Returns the compiled SQL statement
Sets the `GROUP BY`
Whether the query has columns or not
Sets a `HAVING` condition
Sets a 'JOIN' condition
Sets a `OR` for a `HAVING` condition
Resets the internal collections
Start a sub-select
Start a `UNION`
Start a `UNION ALL`
Statement builder
### Constants
### Properties
### Methods
__call()
```php
public function __call(
string $method,
array $params
);
```
Proxied methods to the connection
andHaving()
```php
public function andHaving(
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Sets a `AND` for a `HAVING` condition
appendHaving()
```php
public function appendHaving(
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Concatenates to the most recent `HAVING` clause
appendJoin()
```php
public function appendJoin(
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Concatenates to the most recent `JOIN` clause
asAlias()
```php
public function asAlias( string $asAlias ): Select;
```
The `AS` statement for the query - useful in sub-queries
columns()
```php
public function columns( array $columns ): Select;
```
The columns to select from. If a key is set in the array element, the
key will be used as the alias
distinct()
```php
public function distinct( bool $enable = true ): Select;
```
forUpdate()
```php
public function forUpdate( bool $enable = true ): Select;
```
Enable the `FOR UPDATE` for the query
from()
```php
public function from( string $table ): Select;
```
Adds table(s) in the query
getStatement()
```php
public function getStatement(): string;
```
Returns the compiled SQL statement
groupBy()
```php
public function groupBy( mixed $groupBy ): Select;
```
Sets the `GROUP BY`
hasColumns()
```php
public function hasColumns(): bool;
```
Whether the query has columns or not
having()
```php
public function having(
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Sets a `HAVING` condition
join()
```php
public function join(
string $join,
string $table,
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Sets a 'JOIN' condition
orHaving()
```php
public function orHaving(
string $condition,
mixed $value = null,
int $type = -1
): Select;
```
Sets a `OR` for a `HAVING` condition
reset()
```php
public function reset(): void;
```
Resets the internal collections
subSelect()
```php
public function subSelect(): Select;
```
Start a sub-select
union()
```php
public function union(): Select;
```
Start a `UNION`
unionAll()
```php
public function unionAll(): Select;
```
Start a `UNION ALL`
getCurrentStatement()
```php
protected function getCurrentStatement( string $suffix = "" ): string;
```
Statement builder
## DataMapper\Query\Update
Class
Update Query
- [`Phalcon\DataMapper\Query\AbstractQuery`](#datamapperqueryabstractquery)
- [`Phalcon\DataMapper\Query\AbstractConditions`](#datamapperqueryabstractconditions)
- **`Phalcon\DataMapper\Query\Update`**
`Phalcon\DataMapper\Pdo\Connection`
### Method Summary
Update constructor.
Sets a column for the `UPDATE` query
Mass sets columns and values for the `UPDATE`
Adds table(s) in the query
Whether the query has columns or not
Resets the internal store
Adds the `RETURNING` clause
Sets a column = value condition
### Methods
__construct()
```php
public function __construct(
Connection $connection,
Bind $bind
);
```
Update constructor.
column()
```php
public function column(
string $column,
mixed $value = null,
int $type = -1
): Update;
```
Sets a column for the `UPDATE` query
columns()
```php
public function columns( array $columns ): Update;
```
Mass sets columns and values for the `UPDATE`
from()
```php
public function from( string $table ): Update;
```
Adds table(s) in the query
getStatement()
```php
public function getStatement(): string;
```
hasColumns()
```php
public function hasColumns(): bool;
```
Whether the query has columns or not
reset()
```php
public function reset(): void;
```
Resets the internal store
returning()
```php
public function returning( array $columns ): Update;
```
Adds the `RETURNING` clause
set()
```php
public function set(
string $column,
mixed $value = null
): Update;
```
Sets a column = value condition
Source: https://docs.phalcon.io/5.20/api/phalcon_datamapper/index.mdx