Doctrine DBAL pour PHP : guide complet avec exemples

1. Qu'est-ce que Doctrine DBAL et pourquoi l'utiliser ?

Doctrine DBAL (Database Abstraction Layer) est une bibliothèque PHP puissante qui offre une interface unifiée pour travailler avec différents systèmes de gestion de bases de données relationnelles. Elle fait partie de l'écosystème Doctrine, mais peut être utilisée comme composant autonome. L'objectif principal de DBAL est d'abstraire le développeur des spécificités d'un SGBD particulier (MySQL, PostgreSQL, SQLite, Oracle, SQL Server, etc.), permettant ainsi d'écrire du code portable.

Pourquoi utiliser Doctrine DBAL ? Premièrement, elle simplifie considérablement les opérations courantes : connexion à la base de données, exécution de requêtes, gestion des transactions. Deuxièmement, elle assure la sécurité grâce aux requêtes préparées (prepared statements) et à l'échappement automatique des paramètres, ce qui protège contre les injections SQL. Troisièmement, DBAL fournit un Query Builder pratique pour construire des requêtes complexes sans écrire de SQL brut. Contrairement à un ORM (Object-Relational Mapper) complet, DBAL ne nécessite pas de mapping d'objets et d'entités, ce qui en fait le choix idéal pour les projets où un contrôle direct sur SQL est nécessaire, mais avec des fonctionnalités supplémentaires pratiques.

La bibliothèque est activement maintenue, dispose d'une excellente documentation et est largement utilisée dans le développement professionnel. Elle est à la base de Doctrine ORM et de nombreux frameworks PHP populaires (Symfony, Laravel — via des intégrations).

2. Installation

L'installation de Doctrine DBAL se fait via Composer, le gestionnaire de paquets standard pour PHP. Exécutez la commande suivante dans le terminal à la racine de votre projet :

composer require doctrine/dbal

Après l'installation, un dossier vendor/ et un fichier composer.json avec la dépendance ajoutée apparaîtront dans votre projet. Pour travailler avec un SGBD spécifique, l'installation du pilote PDO correspondant peut être nécessaire (par exemple, ext-pdo_mysql pour MySQL).

3. Démarrage rapide — exemple minimal fonctionnel

Créez un fichier test.php et incluez l'autoloader de Composer. Voici un exemple de connexion à SQLite (base de données intégrée, ne nécessite pas d'installation de serveur) :

<?php
require_once 'vendor/autoload.php';

use Doctrine\DBAL\DriverManager;

// Paramètres de connexion
$connectionParams = [
    'dbname' => 'test.db',
    'driver' => 'pdo_sqlite',
];

// Création de la connexion
$conn = DriverManager::getConnection($connectionParams);

// Création d'une table
$conn->executeStatement('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, email TEXT)');

// Insertion de données
$conn->insert('users', ['name' => 'John Doe', 'email' => 'john@example.com']);

// Récupération des données
$users = $conn->fetchAllAssociative('SELECT * FROM users');
print_r($users);

Ce code crée une base SQLite, une table users, insère un enregistrement et affiche toutes les lignes.

4. Méthodes / fonctions / classes principales

4.1. `DriverManager::getConnection()`

Signature : public static function getConnection(array $params, ?Configuration $config = null, ?EventManager $eventManager = null): Connection

Fonction : Crée et retourne un objet de connexion à la base de données en fonction des paramètres fournis. C'est le point d'entrée de DBAL.

$connectionParams = [
    'dbname' => 'mydb',
    'user' => 'root',
    'password' => 'secret',
    'host' => 'localhost',
    'driver' => 'pdo_mysql',
];
$conn = DriverManager::getConnection($connectionParams);

4.2. `Connection::executeStatement()`

Signature : public function executeStatement(string $sql, array $params = [], array $types = []): int

Fonction : Exécute une requête SQL qui ne retourne pas d'ensemble de lignes (INSERT, UPDATE, DELETE, DDL). Retourne le nombre de lignes affectées.

$conn->executeStatement('UPDATE users SET name = ? WHERE id = ?', ['Jane Doe', 1]);

4.3. `Connection::fetchAllAssociative()`

Signature : public function fetchAllAssociative(string $sql, array $params = [], array $types = []): array

Fonction : Exécute une requête SELECT et retourne toutes les lignes sous forme de tableau associatif.

$users = $conn->fetchAllAssociative('SELECT * FROM users WHERE active = ?', [1]);

4.4. `Connection::insert()`

Signature : public function insert(string $tableName, array $data, array $types = []): int

Fonction : Méthode pratique pour insérer une ligne dans une table. Les données sont automatiquement échappées.

$conn->insert('users', ['name' => 'Alice', 'email' => 'alice@example.com']);

4.5. `Connection::update()`

Signature : public function update(string $tableName, array $data, array $where, array $types = []): int

Fonction : Met à jour les lignes correspondant à la condition $where avec les données fournies.

$conn->update('users', ['name' => 'Bob'], ['id' => 2]);

4.6. `Connection::delete()`

Signature : public function delete(string $tableName, array $where, array $types = []): int

Fonction : Supprime les lignes correspondant à la condition $where.

$conn->delete('users', ['id' => 3]);

4.7. `QueryBuilder` — construction de requêtes complexes

Fonction : Permet de construire des requêtes SQL de manière programmatique et sécurisée, sans écrire de SQL brut.

use Doctrine\DBAL\Query\QueryBuilder;

$queryBuilder = $conn->createQueryBuilder();
$queryBuilder
    ->select('u.id', 'u.name', 'u.email')
    ->from('users', 'u')
    ->where('u.active = :active')
    ->setParameter('active', true)
    ->orderBy('u.name', 'ASC')
    ->setMaxResults(10);

$results = $queryBuilder->fetchAllAssociative();

5. Gestion des transactions

Doctrine DBAL prend en charge les transactions de base de données pour garantir l'intégrité des données :

$conn->beginTransaction();
try {
    $conn->insert('users', ['name' => 'Charlie', 'email' => 'charlie@example.com']);
    $conn->insert('logs', ['action' => 'user_created', 'user_id' => $conn->lastInsertId()]);
    $conn->commit();
} catch (Exception $e) {
    $conn->rollBack();
    echo "Erreur : " . $e->getMessage();
}

6. Bonnes pratiques et conseils

Utilisez toujours des requêtes préparées pour éviter les injections SQL. DBAL le fait automatiquement avec les méthodes comme executeStatement(), fetchAllAssociative(), etc.
Préférez le Query Builder pour les requêtes complexes afin d'améliorer la lisibilité et la maintenabilité du code.
Gérez les connexions avec soin : utilisez un pattern singleton ou un conteneur de dépendances pour éviter de créer plusieurs connexions inutiles.
Utilisez les transactions pour les opérations qui modifient plusieurs tables, afin de garantir la cohérence des données.
Surveillez les performances : activez le logging des requêtes SQL en développement pour identifier les goulots d'étranglement.

7. Conclusion

Doctrine DBAL est un outil indispensable pour tout développeur PHP travaillant avec des bases de données. Elle offre un équilibre parfait entre contrôle direct sur SQL et abstraction pratique, avec une sécurité intégrée contre les injections SQL. Que vous construisiez une petite application ou un système d'entreprise, DBAL vous aidera à écrire un code plus propre, plus sûr et plus portable. Commencez dès aujourd'hui à l'utiliser dans vos projets PHP !