Werken met de database in Drupal 7 – les 6 – Een query dynamisch wijzigen (hook_query_alter)

Een belangrijk kenmerk van dynamische SELECT-query’s is dat andere modules deze query’s “on the fly” kunnen wijzigen. Dit maakt het mogelijk voor andere modules om hun eigen instructies aan een query toe te voegen, waardoor ze het gedrag van de query kunnen beïnvloeden of bijvoorbeeld toegangsbeperkingen op nodes kunnen toepassen. Er zijn drie componenten voor het dynamisch wijzigen van query’s: tagging, meta data en hook_query_alter().

Tagging

Elke dynamische SELECT-query kan één of meerdere “tags” krijgen. Deze tags identificeren het type query, zodat andere modules dit type kunnen herkennen en hun eigen acties eraan kunnen toevoegen. Tags moeten bestaan uit alfanumerieke tekens in kleine letters, volgens dezelfde naamgevingsregels als PHP-variabelen. Gebruik de methode addTag() om een tag aan een query toe te voegen:

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

Om te controleren of een queryobject een bepaalde tag heeft, zijn er drie beschikbare methoden:

<?php
// Geeft TRUE terug als de query de opgegeven tag bevat.
$query->hasTag('example');

// Geeft TRUE terug als de query alle opgegeven tags bevat.
$query->hasAllTags('example1', 'example2');

// Geeft TRUE terug als de query ten minste één van de opgegeven tags bevat.
$query->hasAnyTag('example1', 'example2');
?>

Zowel hasAllTags() als hasAnyTag() accepteren meerdere parameters, waarvan de volgorde niet belangrijk is. Het gebruik van tags is eenvoudig, en er bestaan al veel standaardtags die je kunt gebruiken. Enkele voorbeelden:

node_access

Deze query moet rekening houden met toegangsrechten tot nodes.

translatable

Deze query bevat vertaalbare gegevens.

term_access

Deze query moet rekening houden met toegangsrechten tot termen (taxonomy).

views

Deze query is gelabeld door de Views-module.

Meta data

Query’s kunnen ook meta data bevatten, waarmee extra informatie aan een query kan worden gekoppeld. Meta data kan elke willekeurige PHP-waarde zijn, geïdentificeerd door een string als sleutel.

<?php
$node = node_load($nid);
// ... Maak hier een $query-object aan.
$query->addMetaData('node', $node);
?>

Meta data heeft op zichzelf geen directe invloed op de query; het dient uitsluitend als aanvullende informatie voor hooks die de query kunnen wijzigen. Meta data wordt vooral gebruikt in combinatie met tags. Om toegang te krijgen tot de meta data gebruik je de methode getMetaData():

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

Als er geen meta data is gekoppeld aan de opgegeven sleutel, retourneert deze methode NULL.

hook_query_alter()

Tags en meta data wijzigen de query niet direct. Ze dienen slechts als informatie voor hook_query_alter(), dat de mogelijkheid heeft om de query dynamisch aan te passen. Alle dynamische SELECT-query’s die via hook_query_alter() worden aangeroepen, worden doorgegeven vlak vóór de aanroep van execute(), dus net voordat de query wordt gecompileerd. Dit geeft modules de kans om de query te manipuleren voordat deze wordt uitgevoerd. De hook accepteert één parameter: het queryobject.

<?php
/**
 * Implementatie van hook_query_alter().
 */
function example_query_alter(QueryAlterableInterface $query) {
  // ...
}
?>

Het is ook mogelijk om alleen query’s met een specifieke tag te verwerken via hook_query_TAGNAME_alter(). De volgende code wordt bijvoorbeeld uitgevoerd voor query’s met de tag node_access:

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

Er zijn twee belangrijke observaties over hook_query_alter():

1. De parameter $query wordt niet doorgegeven als referentie. Omdat het een object is, werkt het in PHP 5 altijd als een verwijzing. Het gebruik van & is dus niet nodig. De hook retourneert ook geen waarde.
2. De parameter is expliciet getypeerd als QueryAlterableInterface. Dit zorgt voor extra veiligheid tegen onjuiste parameterwaarden en biedt meer compatibiliteit met toekomstige querytypen dan wanneer enkel SelectQuery was gebruikt.

hook_query_alter() kan vrijwel elke bewerking uitvoeren op het queryobject, zolang het geen recursieve uitvoering van dezelfde query veroorzaakt. De hook kan tags en meta data gebruiken om te bepalen welke wijzigingen moeten worden aangebracht. Moduleontwikkelaars kunnen via deze hook extra velden, joins, voorwaarden enzovoort toevoegen, of toegangscontroles implementeren. Het is ook mogelijk om de oorspronkelijke querystructuur te wijzigen of bestaande elementen te verwijderen.

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

Belangrijk: deze waarden worden by reference teruggegeven, wat betekent dat de hook directe toegang heeft tot de interne structuur van het queryobject. Alle bovengenoemde methoden retourneren arrays, waarvan de structuur wordt beschreven in de documentatie van SelectQuery in het bestand includes/database/select.inc.