Rad sa bazom podataka u Drupal 7 - lekcija 6 - Izmena upita u letu (hook_query_alter)

Važna osobina dinamičkih SELECT upita je mogućnost da drugi moduli menjaju upite „u letu“. Ovo omogućava drugim modulima da ubacuju svoje instrukcije u upit, čime utiču na njegovo ponašanje ili primenjuju promene tokom izvršavanja upita, na primer za definisanje prava pristupa nodovima. Postoje tri komponente za izmene upita u letu: tagging (označavanje), meta podaci i hook_query_alter().

Označavanje (Tagging)

Bilo koji dinamički SELECT upit može biti „tagovan“ sa jednom ili više string vrednosti. Ovi tagovi služe za identifikaciju tipa upita i omogućavaju da se pri vraćanju upita prepozna ta oznaka i doda određena akcija. Tagovi treba da budu zadati u alfanumeričkom obliku malim slovima, prateći ista pravila kao PHP promenljive. Za dodavanje taga upitu koristi se metod addTag().

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

Da proverite da li objekat upita ima određeni tag, postoje tri dostupna metoda:

<?php
// Vraća TRUE ako upit ima dati tag.
$query->hasTag('example');

// Vraća TRUE ako upit ima sve navedene tagove.
$query->hasAllTags('example1', 'example2');

// Vraća TRUE ako upit ima bilo koji od navedenih tagova.
$query->hasAnyTag('example1', 'example2');
?>

Metodi hasAllTags() i hasAnyTag() primaju dva parametra, a njihov redosled nije bitan. Korišćenje tagova je jednostavno i već postoje gotovi tagovi za upotrebu, na primer:

node_access

Upit treba da ima kontrolu pristupa nodovima.

translatable

Upit treba da ima podršku za prevode.

term_access

Upit treba da ima kontrolu pristupa po terminima.

views

Upit označen od strane modula Views.

Meta podaci

Upiti mogu imati i meta podatke prikačene na njih, koji pružaju dodatne informacije za izmene upita u letu. Meta podaci mogu biti bilo koji PHP podaci sa ključem koji je string.

<?php
$node = node_load($nid);
// ... Kreirati $query objekat ovde.
$query->addMetaData('node', $node);
?>

Meta podaci sami po sebi nemaju efekat na upit i služe isključivo kao dodatne informacije za hook_query_alter() i obično se koriste samo ako upit ima tagove. Za pristup vrednostima meta podataka koristi se metod getMetaData().

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

Ako ne postoji meta podatak sa datim ključem, vraća se NULL.

hook_query_alter()

Ni tagovi ni meta podaci ne menjaju sam upit direktno. Oni služe kao informacije za hook_query_alter(), koji može da izvrši bilo kakvu izmenu na dinamičkom SELECT objektu upita. Svi dinamički SELECT upiti se prosleđuju hook_query_alter() pre nego što se pozove execute(), odmah pre kompajliranja upita. Ovo omogućava modulima da manipulišu upitom kako žele. hook_query_alter() prima jedan parametar: objekat upita.

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

Moguće je takođe obrađivati samo upite sa određenim tagom preko hook_query_TAG_NAME_alter(), na primer za tag "node_access":

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

Dva važna zapažanja o hook_query_alter():

1. Parametar $query ne može biti prosleđen po referenci jer je u pitanju objekat, a u PHP5 objekti se po defaultu ne kopiraju prilikom prosleđivanja, tako da referenca nije potrebna. hook_query_alter() ne vraća vrednost.
2. Tip parametra je eksplicitno definisan kao QueryAlterableInterface što pruža bolju zaštitu od grešaka prilikom prosleđivanja neodgovarajućeg tipa. Tip je definisan kao QueryAlterableInterface umesto SelectQuery radi bolje buduće kompatibilnosti.

hook_query_alter() može da izvrši bilo kakvu izmenu na objektu upita osim njegovog izvršavanja na način koji bi doveo do beskonačne petlje. Može koristiti tagove i meta podatke pridružene upitu da odredi koje izmene treba da izvrši. Programeri modula mogu pozvati dodatne metode na objektu upita, poput dodavanja polja, spajanja, uslova itd. ili mogu da upravljaju pravima pristupa podacima direktno. Možete čak i ukloniti deo upita menjajući ga u hook-u.

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

Važno je primetiti da se vrednosti vraćaju po referenci, tako da alter hook ima pristup istim podacima kao i struktura objekta. Svi navedeni metodi vraćaju niz, čija je struktura detaljno opisana u dokumentaciji klase SelectQuery u datoteci includes/database/select.inc.