Travail avec la base de données dans Drupal 7 - leçon 6 - Modification dynamique de requête (hook_query_alter)

Une caractéristique importante des requêtes dynamiques de sélection est la possibilité pour d’autres modules de modifier ces requêtes à la volée. Cela permet à ces modules d’insérer leurs propres instructions dans la requête, influençant ainsi son comportement ou appliquant des modifications pendant l’exécution, par exemple pour gérer les droits d’accès aux nœuds. Trois composants interviennent dans la modification dynamique des requêtes : les tags, les méta-données et le hook hook_query_alter().

Tagging

Toute requête dynamique de sélection peut être "taguée" avec une ou plusieurs chaînes. Ces tags servent à identifier le type de requête et permettent, au retour, de repérer cette chaîne et d’ajouter une action spécifique. Les tags doivent être définis en format alphanumérique en minuscules, selon les mêmes règles que pour les variables PHP. Pour ajouter un tag à une requête, on utilise la méthode addTag().

<?php
$query->addTag('node_access');
?>

Pour vérifier si un objet requête possède un tag donné, on dispose de trois méthodes :

<?php
// TRUE si l’objet requête possède le tag.
$query->hasTag('example');

// TRUE si l’objet requête possède tous les tags suivants.
$query->hasAllTags('example1', 'example2');

// TRUE si l’objet requête possède au moins un des tags suivants.
$query->hasAnyTag('example1', 'example2');
?>

hasAllTags() et hasAnyTag() acceptent deux paramètres, dont l’ordre n’a pas d’importance. L’utilisation des tags est simple et plusieurs tags prêts à l’emploi existent, par exemple :

node_access

Cette requête doit appliquer les restrictions d’accès aux nœuds.

translatable

Cette requête doit prendre en compte la traduction.

term_access

Cette requête doit appliquer les restrictions d’accès aux termes.

views

Cette requête est taguée par le module Views.

Méta-données

Les requêtes peuvent aussi posséder des méta-données attachées, qui fournissent des informations supplémentaires permettant de modifier la requête à la volée. Les méta-données peuvent être n’importe quelle donnée PHP associée à une clé chaîne.

<?php
$node = node_load($nid);
// ... Création de l’objet $query ici.
$query->addMetaData('node', $node);
?>

Les méta-données n’ont pas de sens interne propre et ne modifient pas directement l’objet requête. Elles existent uniquement pour fournir des informations supplémentaires au hook de modification à la volée, et sont principalement utilisées lorsque la requête possède des tags. Pour accéder aux variables fixées via les méta-données, on utilise la méthode getMetaData().

<?php
$node = $query->getMetaData('node');
?>

Si aucune méta-donnée n’est associée à cette clé, la méthode retourne NULL.

hook_query_alter()

Ni les tags ni les méta-données ne modifient directement la requête. Ils fournissent seulement des informations au hook hook_query_alter(), qui peut effectuer n’importe quelle action sur l’objet requête dynamique. Toutes les requêtes dynamiques de sélection sont passées à hook_query_alter() juste avant l’appel à execute(), avant la compilation de la requête. Cela permet aux modules de manipuler la requête à leur guise. hook_query_alter() prend un seul paramètre : l’objet requête.

<?php
/**
* Implémentation de hook_query_alter().
*/
function example_query_alter(QueryAlterableInterface $query) {
  // ...
}
?>

Il est également possible de traiter uniquement les requêtes portant un tag spécifique via le hook hook_query_TAG_NAME_alter(). Le code suivant s’exécute pour les requêtes taguées "node_access" :

<?php
function example_query_node_access_alter(QueryAlterableInterface $query) {
  // ...
}
?>

Deux points importants concernant hook_query_alter() :

1. Le paramètre $query ne peut pas être passé par référence. En PHP5, les objets sont toujours passés par référence implicite, donc ce n’est pas nécessaire. De plus, hook_query_alter() ne retourne aucune valeur.
2. Le type du paramètre est explicitement défini comme QueryAlterableInterface, ce qui garantit une meilleure sécurité en empêchant la transmission d’un mauvais type. Ce type est défini comme QueryAlterableInterface plutôt que SelectQuery pour assurer une meilleure compatibilité future.

hook_query_alter() peut effectuer toute modification sur l’objet requête, excepté exécuter la requête (ce qui pourrait provoquer une boucle infinie). Il peut utiliser les tags et méta-données associés à la requête pour décider de l’action à mener. Les développeurs peuvent également appeler des méthodes sur l’objet requête comme l’ajout de champs, jointures, conditions, etc., ou gérer l’accès aux données directement. Vous pouvez aussi supprimer un premier type de requête en le modifiant dans le hook.

<?php
$fields =& $query->getFields();
$expressions =& $query->getExpressions();
$tables =& $query->getTables();
$order =& $query->getOrderBy();
$where =& $query->conditions();
$having =& $query->havingConditions();
?>

Notez que les valeurs sont retournées par référence, donc le hook alter a accès aux mêmes données que la structure de l’objet. Toutes ces méthodes retournent un tableau dont la structure est documentée dans la documentation de SelectQuery dans includes/database/select.inc.