Requêtes statiques
Les requêtes SELECT les plus courantes dans Drupal sont des requêtes statiques utilisant la méthode query() de l’objet de connexion à la base de données.
Les requêtes statiques sont transmises à la base de données presque telles quelles.
Exemple :
$database = \Drupal::database();
$query = $database->query("SELECT id, example FROM {mytable}");
$result = $query->fetchAll();
Seules les requêtes SELECT très simples doivent utiliser la méthode statique query(). Vous devez utiliser une requête dynamique si vous avez besoin de requêtes plus complexes, d’une génération dynamique des requêtes ou de variabilité.
N’utilisez pas cette fonction pour des requêtes simples INSERT, UPDATE ou DELETE. Elles doivent être gérées via insert(), update() et delete() respectivement. Pour des requêtes DELETE plus complexes impliquant plusieurs tables, voir Requêtes DELETE complexes.
Arguments
La méthode query() de l’objet de connexion à la base de données prend trois arguments :
- $query : la requête à exécuter. Utilisez des placeholders si nécessaire et entourez tous les noms de tables d’accolades.
- $args : un tableau des valeurs des placeholders à substituer dans la requête.
- $options : un tableau d’options pour contrôler le comportement de la requête (optionnel).
Préfixe des noms de table
Dans les requêtes statiques, tous les noms de tables doivent être entourés d’accolades {...}.
Entourer les noms de tables d’accolades permet au système de base de données d’ajouter un préfixe si nécessaire. Le préfixe permet d’exécuter plusieurs sites à partir d’une seule base de données ou, dans certains cas, de partager certaines tables entre sites. Cela évite aussi la fuite de données entre le site hôte et les tests.
Placeholders
Les placeholders indiquent où une valeur littérale sera insérée dans la requête lors de son exécution. En les séparant de la requête elle-même, nous permettons à la base de données de différencier la syntaxe SQL et les valeurs fournies par l’utilisateur, ce qui évite les injections SQL.
$query = $database->query("SELECT id, example FROM {mytable} WHERE created > :created", [
':created' => REQUEST_TIME - 3600,
]);
Le code ci-dessus sélectionnera tous les identifiants et exemples de mytable créés durant la dernière heure (3600 secondes). Le placeholder :created sera remplacé dynamiquement par la valeur REQUEST_TIME - 3600 au moment de l’exécution.
Une requête peut contenir n’importe quel nombre de placeholders, mais tous doivent avoir des noms uniques, même s’ils ont la même valeur. Selon le cas, le tableau des placeholders peut être passé en ligne (comme ci-dessus) ou construit à l’avance et transmis. L’ordre des éléments dans le tableau n’a pas d’importance.
Les placeholders commençant par "db_" sont réservés à l’usage interne du système et ne doivent jamais être utilisés explicitement.
Notez que les placeholders ne doivent pas être échappés ni entourés de guillemets, quel que soit leur type. Étant donnés qu’ils sont transmis séparément au serveur de base de données, ce dernier peut différencier lui-même la chaîne de requête et la valeur.
// FAUX (guillemets autour du placeholder :type)
$result = $database->query("SELECT example FROM {mytable} WHERE type = ':type'", [
':type' => 'mytype',
]);
// CORRECT (pas de guillemets autour du placeholder :type)
$result = $database->query("SELECT example FROM {mytable} WHERE type = :type", [
':type' => 'mytype',
]);
Les placeholders ne peuvent pas être utilisés pour les noms de colonnes ou de tables. Si ces derniers proviennent d’une saisie non sécurisée, ils doivent être traités avec $database->escapeTable().
Tableaux de placeholders
Le niveau base de données de Drupal offre une fonctionnalité supplémentaire pour les placeholders. Si la valeur passée pour un placeholder est un tableau, elle sera automatiquement développée en une liste séparée par des virgules correspondant au placeholder. Cela signifie que les développeurs n’ont pas à se soucier du nombre de placeholders nécessaires.
Un exemple illustre ce comportement :
$result = $database->query("SELECT * FROM {mytable} WHERE id IN (:ids[])", [':ids[]' => [13, 42, 144]]);
Les deux instructions suivantes sont équivalentes à celle ci-dessus :
$result = $database->query("SELECT * FROM {mytable} WHERE id IN (:ids_1, :ids_2, :ids_3)", [
':ids_1' => 13,
':ids_2' => 42,
':ids_3' => 144,
]);
$result = $database->query("SELECT * FROM {mytable} WHERE id IN (13, 42, 144)");
Options de requête
Le troisième paramètre de la méthode query() de l’objet de connexion à la base de données est un tableau d’options qui définit le comportement de la requête. Habituellement, seules deux directives sont utilisées par la plupart des requêtes. Les autres valeurs sont principalement internes.
La clé "target" indique la cible à utiliser. Par défaut, la valeur est "default". Actuellement, la seule autre valeur autorisée est "replica", ce qui indique que la requête doit être exécutée sur un serveur de réplique, si disponible.
La clé "fetch" indique comment les enregistrements retournés seront récupérés. Les valeurs autorisées sont PDO::FETCH_OBJ, PDO::FETCH_ASSOC, PDO::FETCH_NUM, PDO::FETCH_BOTH ou une chaîne représentant le nom d’une classe. Si une chaîne est donnée, chaque enregistrement sera récupéré dans un nouvel objet de cette classe. Le comportement des autres valeurs est défini par PDO et récupère les enregistrements comme un objet stdClass, un tableau associatif, un tableau numérique ou un tableau combiné respectivement. Voir http://php.net/manual/en/pdostatement.fetch.php. Par défaut, PDO::FETCH_OBJ est utilisé, et il est recommandé de s’y tenir sauf raison particulière.
Dans l’exemple suivant, la requête s’exécute sur le serveur de réplique si disponible, et les enregistrements sont récupérés sous forme de tableau associatif.
$result = $database->query("SELECT id, example FROM {mytable}", [], [
'target' => 'replica',
'fetch' => PDO::FETCH_ASSOC,
]);
L’objet résultat retourné par la méthode query() peut être utilisé pour obtenir chaque ligne retournée, puis chaque colonne. Dans l’exemple suivant, la variable $result contient toutes les lignes retournées, puis les lignes sont extraites une par une dans la variable $row avec fetchAssoc() :
$sql = "SELECT name, quantity FROM goods WHERE vid = :vid";
$result = $database->query($sql, [':vid' => $vid]);
if ($result) {
while ($row = $result->fetchAssoc()) {
// Faites quelque chose avec :
// $row['name']
// $row['quantity']
}
}
Requêtes DELETE complexes
L’utilisation d’une requête statique est une manière simple et compacte d’exprimer une requête DELETE qui supprime depuis plusieurs tables en une seule expression.
Exemple :
$database = \Drupal::database();
$database->query("DELETE {table1}, {table2} FROM {table1} INNER JOIN {table2} ON {table1}.id = {table2}.id WHERE {table1}.id=:recno", [":recno" => 2]);
(Supprime la ligne des tables table1 et table2)