Travail avec la base de données dans Drupal 7 - leçon 5 - Extenders (Extensions)

Les requêtes de sélection supportent les extensions (extenders). Une extension permet d’ajouter des fonctionnalités à une requête de sélection lors de son exécution. Cette fonctionnalité peut être une méthode supplémentaire ou modifier le comportement d’une méthode existante.

Pour cela, des patterns de programmation orientée objet sont utilisés ; les extensions implémentent le Decorator Pattern. Elles ajoutent des responsabilités supplémentaires à un objet dynamique en fournissant une sous-classe alternative flexible pour la méthode étendue.

Utilisation des Extenders (extensions)

Pour utiliser une extension, vous devez disposer d’un objet requête. Pour cet objet, la méthode extend() retourne un nouvel objet qui sera utilisé à la place de l’objet requête actuel. Par exemple :

<?php
$query = $query->extend('PagerDefault');
?>

Dans cet exemple, un nouvel objet PagerDefault est créé, contenant l’objet requête original, et retourne ce nouvel objet. $query peut être utilisé sans extension, mais avec elle, l’objet obtient des fonctionnalités supplémentaires. Notez aussi que $query sera remplacé par la valeur retournée par extend() et que l’ancienne valeur ne sera pas conservée. L’exemple suivant illustre cela :

<?php
$query = db_select('node', 'n');
$query
  ->fields('n', array('nid', 'title'))
  ->extend('PagerDefault')   // Cette ligne retourne un nouvel objet PagerDefault.
  ->limit(5);               // Cette ligne fonctionne, car c’est l’objet PagerDefault qui est appelé.

// Le retour de extend() n’a jamais été assigné à une variable, donc $query est toujours l’objet Select d’origine.
$query->orderBy('title');

// Cette ligne exécute l’objet Select, pas l’extension. L’extension n’existe plus.
$result = $query->execute();
?>

Pour éviter ce problème, il est recommandé d’assigner le résultat de extend() à la même variable que l’objet requête d’origine :

<?php
$query = db_select('node', 'n')->extend('PagerDefault')->extend('TableSort');
$query->fields(...);
// ...
?>

Cela garantit que $query a bien toutes les extensions appliquées. Plusieurs extensions peuvent être appliquées à un objet, mais leur ordre peut avoir de l’importance. Par exemple, un objet étendu avec TableSort doit d’abord être étendu avec PagerDefault.

Création de nouvelles extensions

Une extension est simplement une classe qui implémente l’interface SelectQueryInterface et qui prend deux paramètres dans son constructeur : la requête de sélection et un objet DatabaseConnection. L’extension doit implémenter les méthodes de SelectQueryInterface et les déléguer à la requête dans son constructeur.

Dans la plupart des cas, cela se fait en étendant la classe SelectQueryExtender, qui gère tout en interne. En pratique, les extensions sont des classes qui étendent SelectQueryExtender. Le nom de cette classe est celui qui doit être passé à extend().

Ajouter ou redéfinir des méthodes dépend uniquement de la classe d’extension. Toute méthode non redéfinie sera directement transmise à l’objet requête sous-jacent. Quand une méthode est redéfinie, l’extension peut ou non appeler l’objet requête sous-jacent, mais elle doit retourner la valeur attendue par l’interface SelectQuery. Dans la plupart des cas, cela signifie retourner l’objet requête ou l’extension.

Voici un exemple illustrant ce qui précède :

<?php
class ExampleExtender extends SelectQueryExtender {

  /**
   * Redéfinit la méthode orderBy().
   */
  public function orderBy($field, $direction = 'ASC') {
    return $this;
  }

  /**
   * Ajoute une méthode personnalisée.
   */
  public function orderByForReal($field, $direction = 'ASC') {
    $this->query->orderBy($field, $direction);
    return $this;
  }
}
?>

Dans cet exemple, la méthode orderBy() est redéfinie sans rien ajouter, tandis qu’une méthode additionnelle orderByForReal() implémente le tri réel. Les deux méthodes retournent l’objet requête, ce qui permet de conserver la chaîne d’appels.

Tout module peut déclarer une extension. Le noyau Drupal fournit deux bonnes extensions : PagerDefault et TableSort.

Support multi-base de données

La méthode extend() fonctionne comme db_select() : l’extension recherche le nom de la classe avec le suffixe correspondant au pilote de base de données. Vous pouvez donc définir ExampleExtender_pgsql ainsi qu’une classe ExampleExtender qui sera utilisée si la première n’est pas disponible.