Doctrine DBAL Documentation

Doctrine DBAL is structured into two main layers: a wrapper layer and a driver layer.

Wrapper Layer

Applications typically interact directly with these wrapper components, which provide a consistent API regardless of the underlying database:

• Doctrine\DBAL\Connection (wraps a driver connection)
• Doctrine\DBAL\Statement (wraps a driver statement)
• Doctrine\DBAL\Result (wraps a driver result)

Driver Layer

The driver layer abstracts specific PHP database APIs (like pdo_mysql or mysqli) using four core interfaces:

• Doctrine\DBAL\Driver
• Doctrine\DBAL\Driver\Connection
• Doctrine\DBAL\Driver\Statement
• Doctrine\DBAL\Driver\Result

A Doctrine\DBAL\Driver implementation is responsible for translating connection parameters and acting as a factory for platform, schema manager, and exception converter components.

Doctrine DBAL provides a type translation system that converts between database-specific SQL types and PHP data types. This allows for database-independent applications by handling the conversion to and from PHP values and generating platform-independent SQL for any Doctrine\\DBAL\\\ Types\\\ Type.

Key characteristics:

• Abstraction: Types are abstracted across all supported database vendors.
• Flyweight Pattern: Type instances are flyweights. There is only ever one instance of a specific type, and instances are not allowed to contain any state.
• ORM Usage: If you are using the Doctrine ORM, you generally do not need to interact with the Type system directly unless you are implementing database vendor-specific types that are not included in Doctrine DBAL.

You can access the QueryBuilder by calling createQueryBuilder() on a Doctrine\DBAL\Connection instance. The QueryBuilder object provides methods to programmatically build SQL statements for SELECT, INSERT, UPDATE, and DELETE queries.

<?php

$conn = DriverManager::getConnection([/*..*/]);
$queryBuilder = $conn->createQueryBuilder();

When upgrading from 3.4, note the following deprecations regarding statement execution:

1. Statement::bindParam() and Driver Statement::bindParam() are deprecated. Use bindValue() instead.
2. Not passing a $type to Statement::bindParam() or ::bindValue() is deprecated. Always pass the corresponding parameter type.
3. Passing $params directly to Statement::execute(), Statement::executeQuery(), or Statement::executeStatement() is deprecated. Use bindParam() or bindValue() to bind parameters before execution.

The methods QueryBuilder::resetQueryParts() and QueryBuilder::resetQueryPart() are deprecated. Use the following specific replacements based on the part you wish to reset:

Extending library behavior via the Doctrine Event Manager is deprecated.

Connection/Platform Events:

• AbstractPlatform::$_eventManager, getEventManager(), setEventManager()
• Connection::$_eventManager, getEventManager()

Connection postConnect replacements:

• OracleSessionInit $\rightarrow$ Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession
• SQLiteSessionInit $\rightarrow$ Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys
• SQLSessionInit $\rightarrow$ Implement a custom middleware.

Transaction/Schema Events:

• For transaction events (onTransactionBegin, etc.), implement a driver middleware or a custom wrapper connection.
• For schema definition/manipulation events, use a custom schema manager or extend the platform class directly.

The url parameter in DriverManager::getConnection() is deprecated. Use the new DsnParser to parse a database URL into connection parameters.

Before:

$connection = DriverManager::getConnection(
    ['url' => 'mysql://my-user:t0ps3cr3t@my-host/my-database']
);

After:

$dsnParser  = new DsnParser(['mysql' => 'pdo_mysql']);
$connection = DriverManager::getConnection(
    $dsnParser->parse('mysql://my-user:t0ps3cr3t@my-host/my-database')
);

The object name parser no longer implicitly quotes identifiers for reserved keywords (e.g., select) or unquoted identifiers preceded by a quoted identifier (e.g., "inventory".product).

To ensure the original case of an identifier is preserved on platforms like PostgreSQL, Oracle, or IBM DB2, you must explicitly quote it (e.g., use "select" instead of select).