Trabajar con una base de datos en Drupal 7 - Lección 5 - Extensores

Las consultas de selección admiten extensiones (extenders). Una extensión permite añadir funcionalidad a una consulta en tiempo de ejecución. Esta funcionalidad puede ser un método adicional o una modificación del comportamiento de un método existente.

En programación orientada a objetos, esto se implementa mediante patrones de diseño. Las extensiones implementan el patrón Decorator. Añaden responsabilidades adicionales a un objeto dinámicamente, proporcionando una alternativa flexible a la herencia directa mediante el uso de métodos de extensión.

Uso de extensiones (Extenders)

Para usar una extensión necesitas tener un objeto de consulta. El método extend() del objeto consulta devuelve un nuevo objeto que debe utilizarse en lugar del original. Por ejemplo:

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

En este ejemplo se crea un nuevo objeto de consulta PagerDefault, que contiene la consulta original, y se devuelve el nuevo objeto. $query puede usarse sin extensiones, pero con ellas el objeto obtiene funcionalidades adicionales. Ten en cuenta que $query es sobrescrito por el resultado del método extend(). Si no se guarda este valor, se pierde la extensión. Veamos otro ejemplo:

<?php
$query = db_select('node', 'n');
$query
  ->fields('n', array('nid', 'title'))
  ->extend('PagerDefault')   // Esta línea devuelve un nuevo objeto PagerDefault.
  ->limit(5);                // Esta línea funciona, porque llama al objeto PagerDefault.

// El valor de retorno de extend() no se guardó, así que $query sigue siendo un objeto Select.
$query->orderBy('title');

// Esta línea ejecuta el objeto Select, no el extender. El extender ya no existe.
$result = $query->execute();
?>

Para evitar problemas, se recomienda guardar el resultado de extend() en la misma variable de la consulta:

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

Así $query es el objeto completamente extendido desde el principio. Además, puedes aplicar múltiples extensiones a una consulta, pero el orden importa. Por ejemplo, para usar TableSort, primero debe aplicarse PagerDefault.

Creación de nuevas extensiones

Una extensión es simplemente una clase que implementa SelectQueryInterface y acepta dos parámetros en su constructor: la consulta de selección y un objeto DatabaseConnection. La extensión debe implementar los métodos de la interfaz y delegar las llamadas al objeto de consulta recibido en el constructor.

En la práctica, esto suele hacerse extendiendo la clase SelectQueryExtender, que maneja internamente la lógica de delegación. Así, cualquier clase que extienda SelectQueryExtender puede usarse como extensión. El nombre de esta clase es el que se pasa al método extend().

El agregar o sobrescribir métodos depende únicamente de la clase de extensión. Cualquier método no sobrescrito será delegado automáticamente al objeto consulta original. Cuando se sobrescribe un método, la extensión puede o no llamar al objeto consulta, pero debe retornar un valor esperado por la interfaz SelectQuery, generalmente el propio objeto o un nuevo extender.

El siguiente ejemplo lo ilustra:

<?php
class ExampleExtender extends SelectQueryExtender {

  /**
   * Sobrescribe el método orderBy sin realizar acción.
   */
  public function orderBy($field, $direction = 'ASC') {
    return $this;
  }

  /**
   * Método personalizado que sí aplica la ordenación real.
   */
  public function orderByForReal($field, $direction = 'ASC') {
    $this->query->orderBy($field, $direction);
    return $this;
  }
}
?>

En este ejemplo, sobrescribimos el método orderBy() pero no realizamos ninguna acción con él. En cambio, agregamos un nuevo método orderByForReal() que realiza la ordenación correctamente. Ambos devuelven el objeto consulta para conservar la cadena de métodos.

Cualquier módulo puede declarar extensiones. El núcleo de Drupal proporciona dos extensiones muy útiles: PagerDefault y TableSort.

Compatibilidad con múltiples bases de datos

El método de extensión funciona como db_select(). Busca una clase que coincida con el nombre base y un sufijo específico del driver de la base de datos. Por lo tanto, puedes definir clases como ExampleExtender_pgsql además de ExampleExtender, y se usará la más adecuada según el entorno.