Werken met de database in Drupal 7 – les 3 – Statistische query’s (SELECT)

De meest gebruikte vorm van een query in Drupal is de statische query. Een statische query wordt letterlijk doorgestuurd naar de database. Alleen een SELECT-query kan statisch zijn.

Gebruik statische query’s uitsluitend voor zeer eenvoudige bewerkingen. Wanneer je complexe, dynamisch opgebouwde of later aan te passen query’s moet schrijven, gebruik dan dynamische query’s.

Een eenvoudige manier om een statische query uit te voeren is via de querymethode:

<?php
$result = $conn->query("SELECT nid, title FROM {node}");
?>

De voorkeur gaat echter uit naar de procedurele wrapper:

<?php
$result = db_query("SELECT nid, title FROM {node}");
?>

De bovenstaande aanroep van db_query() is gelijkwaardig aan:

<?php
$result = Database::getConnection()->query("SELECT nid, title FROM {node}");
?>

Laten we eens bekijken waarom het gebruik van db_query() de betere keuze is dan rechtstreeks de Database-class aan te roepen.

db_query() accepteert drie argumenten: de querystring zelf (met placeholders waar nodig en tabelnamen tussen accolades), een array met waarden voor de placeholders, en een optionele array met configuratieparameters voor de uitvoering van de query.

Voorvoegsels (Prefixing)

In statische query’s moeten alle tabelnamen tussen accolades {} staan. Dit maakt het mogelijk om automatisch een voorvoegsel (prefix) toe te voegen aan tabelnamen. Prefixes maken het mogelijk om meerdere Drupal-sites in één database te gebruiken, waarbij elke site zijn eigen prefix heeft, bijvoorbeeld site1_ of site2_.

Placeholders

Placeholders zijn tekstmarkeringen die worden vervangen door waarden. Door placeholders te gebruiken, kan Drupal gebruikersinvoer scheiden van SQL-syntaxis en zo SQL-injecties voorkomen.

<?php
$result = db_query("SELECT nid, title FROM {node} WHERE created > :created", array(
  ':created' => REQUEST_TIME - 3600,
));
?>

Deze query selecteert alle nodes die zijn aangemaakt in het afgelopen uur. De placeholder :created wordt dynamisch vervangen door de waarde REQUEST_TIME - 3600. Een query kan een onbeperkt aantal placeholders hebben, maar elk moet een unieke naam hebben, ook al hebben sommige dezelfde waarde.

De array met placeholders kan inline worden opgegeven of vooraf worden gedefinieerd en later doorgegeven. De volgorde in de array maakt niet uit. Placeholders die beginnen met db_ zijn gereserveerd voor Drupal zelf en mogen niet handmatig worden gebruikt.

Let op dat je placeholders niet tussen aanhalingstekens mag plaatsen – Drupal verwerkt de juiste escaping automatisch.

<?php
// FOUT:
$result = db_query("SELECT nid, title FROM {node} WHERE type = ':type'", array(
  ':type' => 'page',
));

// GOED:
$result = db_query("SELECT nid, title FROM {node} WHERE type = :type", array(
  ':type' => 'page',
));
?>

Placeholders mogen niet worden gebruikt voor tabel- of kolomnamen – alleen voor tekstuele of numerieke waarden.

Arrays als placeholders

De database-laag van Drupal ondersteunt ook arrays als placeholderwaarden. Wanneer je een array doorgeeft, wordt deze automatisch omgezet in een door komma’s gescheiden lijst. Zo hoef je niet handmatig het juiste aantal placeholders te tellen. Bijvoorbeeld:

<?php
db_query("SELECT * FROM {node} WHERE nid IN (:nids)", array(':nids' => array(13, 42, 144)));

// Intern wordt dit omgezet naar:
db_query("SELECT * FROM {node} WHERE nid IN (:nids_1, :nids_2, :nids_3)", array(
  ':nids_1' => 13,
  ':nids_2' => 42,
  ':nids_3' => 144,
));
// Wat resulteert in:
db_query("SELECT * FROM {node} WHERE nid IN (13, 42, 144)");
?>

Queryparameters

Het derde argument van db_query() is een array met instellingen voor de query. Deze bepaalt hoe de query moet worden uitgevoerd. De twee meest gebruikte sleutels zijn target en fetch.

target specificeert welk databasekanaal moet worden gebruikt. Als dit niet is ingesteld, gebruikt Drupal default. Het enige andere geldige doel is slave, wat betekent dat de query naar een replicaserver (read-only) moet worden gestuurd, indien beschikbaar.

fetch bepaalt hoe de resultaten worden opgehaald. Mogelijke waarden zijn onder andere:

• PDO::FETCH_OBJ – resultaten als objecten (standaard).
• PDO::FETCH_ASSOC – resultaten als associatieve arrays.
• PDO::FETCH_NUM – resultaten als genummerde arrays.
• PDO::FETCH_BOTH – resultaten als zowel genummerde als associatieve arrays.

Je kunt ook een klassenaam opgeven – in dat geval retourneert Drupal elke rij als een instantie van die klasse.

Zie ook: PDOStatement::fetch().

Het volgende voorbeeld voert een query uit op de slave-server (indien aanwezig) en retourneert de resultaten als associatieve array:

<?php
$result = db_query("SELECT nid, title FROM {node}", array(), array(
  'target' => 'slave',
  'fetch' => PDO::FETCH_ASSOC,
));
?>