Concepts généraux

Le niveau base de données de Drupal est construit au-dessus de la bibliothèque PDO de PHP. PDO fournit une API orientée objet unifiée pour accéder à différentes bases de données, mais ne propose pas d’abstraction des différents dialectes SQL utilisés par ces bases.

Drivers

Comme chaque base de données requiert un type d’interaction différent, le niveau base de données de Drupal nécessite un driver pour chaque type de base. Un driver est constitué d’une série de fichiers situés dans include/database/driver, où driver est une chaîne représentant la clé unique de ce driver. Généralement, la clé est le nom de la base en minuscules, par exemple « mysql », « pgsql » ou « mycustomdriver ».

Chaque driver est constitué de plusieurs classes qui héritent de classes parent dans le système de base de données de base. Ces classes spécifiques au driver peuvent redéfinir tout comportement nécessaire pour supporter correctement ce type de base. Les classes spécifiques sont toujours nommées en ajoutant un suffixe souligné suivi du nom du driver à la classe parent, par exemple InsertQuery_mysql pour la version MySQL de InsertQuery.

Connexions

Une connexion est un objet de la classe DatabaseConnection, qui hérite de PDO. Pour chaque base de données à laquelle Drupal se connecte, un objet connexion est associé. Cet objet doit être subdivisé en sous-classes pour chaque driver spécifique.

Pour accéder (et ouvrir si nécessaire) à l’objet de connexion, utilisez :

$database = \Drupal::database();
// Ou
$database = \Drupal::service('database');

Si les services ne sont pas encore disponibles, \Drupal\Core\Database\Database::getConnection() permet d’obtenir la connexion à la base.

Pour plus d’informations sur l’objectif et la clé de connexion, voir la page de documentation sur la configuration de la base de données.

Pour accéder à la connexion active courante, utilisez :

$conn =  \Drupal\Core\Database\Database::getConnection();

Cela récupère la cible par défaut de la connexion active.

Notez que dans la grande majorité des cas, il n’est pas nécessaire de demander directement l’objet de connexion. Des wrappers procéduraux s’en chargent pour vous. Vous n’aurez besoin d’accéder directement à la connexion que si vous manipulez plusieurs bases et ne voulez pas changer la base active.

Pour définir la connexion active, utilisez :

$conn = \Drupal\Core\Database\Database::setActiveConnection('external');

Voir la section suivante, Configuration de la base de données, pour plus de détails sur les clés et cibles de connexion.

Requêtes

Une requête est une instruction SQL envoyée à la connexion base de données. Le système supporte six types de requêtes : statique, dynamique, insertion, mise à jour, suppression et fusion. Certaines requêtes sont écrites sous forme de chaînes SQL préparées, d’autres utilisent des constructeurs d’objets orientés (builders). Un « objet requête » désigne une instance d’un de ces builders pour un type donné.

Statements

L’objet statement est le résultat d’une requête de sélection. Il est toujours de type DatabaseStatement ou d’une sous-classe. DatabaseStatement étend PDOStatement.

Drupal utilise des statements préparés pour toutes les requêtes. Un statement préparé est un modèle de requête dans lequel les valeurs seront insérées lors de l’exécution. On peut voir un statement préparé comme une fonction SQL appelée avec des paramètres.

Avec PDO classique, on prépare un statement explicitement puis on l’exécute avec des valeurs liées aux placeholders dans la requête. Le statement peut être exécuté plusieurs fois et il représente un ensemble de résultats. Statement et jeu de résultats sont synonymes, mais seulement après exécution.

Drupal ne donne pas directement accès au statement préparé. Le développeur utilise l’objet requête ou une chaîne SQL pour exécuter la requête, et un objet statement est retourné. Ainsi, « objet statement » et « objet jeu de résultats » sont presque synonymes.