Travail avec la base de données dans Drupal 7 - leçon 9 - Requêtes de mise à jour (UPDATE)

Les requêtes de mise à jour doivent toujours utiliser le constructeur de requêtes. Les différentes bases de données ont des gestionnaires spécifiques pour les LOB (Large OBject, tels que TEXT dans MySQL) et les champs BLOB (Binary Large OBject), donc un niveau d’abstraction est nécessaire pour que les pilotes individuels implémentent leurs gestionnaires spécifiques.

Les requêtes de mise à jour commencent toujours par la fonction db_update() :

<?php
$query = db_update('node', $options);
?>

En créant cet objet requête de mise à jour, nous allons modifier une ou plusieurs entrées dans la table node. Notez que les accolades ne sont pas nécessaires, le constructeur de requêtes gère lui-même les noms des tables.

L’objet requête de mise à jour utilise une API fluide (fluent API). Ainsi, toutes les méthodes (sauf execute()) retournent l’objet requête lui-même, ce qui permet de chaîner les appels. Souvent, cela signifie que la requête ne sera pas assignée à une variable.

Les requêtes de mise à jour sont simples et consistent en un ensemble clé/valeur défini avec un ensemble de conditions WHERE. La structure complète des clauses WHERE sera abordée en détail dans une prochaine leçon, ici nous l’évoquons simplement.

Voici un exemple typique de requête de mise à jour :

<?php
/* Cet exemple montre comment mettre à jour des enregistrements dans la table node */
$num_updated = db_update('node')
  ->fields(array(
    'uid' => 5,
    'status' => 1,
  ))
  ->condition('created', REQUEST_TIME - 3600, '>=')
  ->execute();
?>

L’exemple ci-dessus est équivalent à la requête SQL suivante :

UPDATE {node} SET uid=5, status=1 WHERE created >= 1221717405;

Ce code mettra à jour tous les enregistrements de la table node créés dans la dernière heure, en définissant uid à 5 et status à 1. La méthode fields() accepte un tableau associatif décrivant quels champs mettre à jour et quelles nouvelles valeurs y insérer. Notez que contrairement aux requêtes d’insertion, UpdateQuery::fields() supporte uniquement les tableaux associatifs. L’ordre dans le tableau fields et l’ordre des appels aux méthodes n’ont pas d’importance.

La méthode execute() retourne le nombre de lignes mises à jour par la requête. Notez que ce nombre ne correspond pas forcément à toutes les lignes qui satisfont la condition WHERE. Par exemple, s’il existe déjà des nœuds avec uid=5 et status=1, ces nœuds peuvent satisfaire la condition WHERE mais ne seront pas modifiés car leurs valeurs correspondent déjà à celles demandées. Ainsi, le nombre retourné par la requête ne reflète pas toujours précisément combien de lignes ont uid=5 et status=1 actuellement.