Werken met de database in Drupal 7 – Les 1 – Drupal Database API

Als je eerder modules hebt geschreven voor Drupal 6, zal het voor jou niet moeilijk zijn om over te stappen naar de nieuwe Database API van Drupal 7. De nieuwe DB API werkt op basis van de PHP-extensie PDO, waardoor het met verschillende databases kan werken, zoals MySQL, PostgreSQL, MSSQL en mogelijk Oracle. Wat eenvoud betreft, is het even wennen aan de nieuwe syntaxis — het schrijven van ruwe SQL-query’s blijft voor velen vertrouwd.

Hier is een stukje uit de officiële documentatie:

De Drupal 7 Database API biedt een gestandaardiseerde, intuïtieve abstractielaag voor toegang tot databaseservers. Deze API is ontworpen om zo veel mogelijk van de kracht en syntaxis van SQL te behouden, maar daarnaast:

• maakt het eenvoudig om met meerdere databaseservers te werken;
• staat ontwikkelaars toe om complexere databasefuncties te implementeren, zoals transacties;
• biedt een gestructureerde interface voor het dynamisch opbouwen van query’s;
• zorgt voor ingebouwde beveiliging en naleving van best practices;
• geeft modules een nette interface om query’s van de site te onderscheppen en te wijzigen;

• De belangrijkste documentatie van de Database API bevindt zich in de commentaren binnen de broncode. De handbook op drupal.org biedt een inleidende uitleg voor moduleontwikkelaars die beter willen leren omgaan met databases vanuit een beheerdersperspectief. De handleiding dekt echter niet alle mogelijkheden van de API.

• De Database API is ontwikkeld volgens de principes van objectgeoriënteerd programmeren, en dit document gaat ervan uit dat je hier ten minste gedeeltelijk mee bekend bent. Toch blijven de meeste standaardbewerkingen beschikbaar in functionele vorm, zodat ontwikkelaars kunnen kiezen welke aanpak ze willen gebruiken.

Belangrijkste concepten van de Drupal Database API

De database-abstractielaag (de db layer) in Drupal is gebouwd op de PHP PDO-bibliotheek. PDO biedt een uniforme, objectgeoriënteerde interface voor toegang tot verschillende databases, maar het biedt geen abstractie voor de verschillende SQL-dialecten van deze systemen.

Drivers

Omdat verschillende databases verschillende manieren van interactie vereisen, heeft de Drupal db layer voor elk type database een aparte driver nodig. Een driver bestaat uit een reeks bestanden in includes/database/driver, waarbij driver de naam is van de specifieke database in kleine letters, zoals “mysql”, “pgsql” of “mycustomdriver”.

Elke driver bevat meerdere klassen die afgeleid zijn van de basisklassen in de kern van Drupal. Deze driverklassen kunnen elk gewenst gedrag overschrijven om ondersteuning te bieden voor specifieke databases. De naam van de driverklasse volgt altijd het patroon van de hoofdklasse, gevolgd door een underscore en de naam van de driver in kleine letters. Bijvoorbeeld: de MySQL-specifieke versie van InsertQuery heet InsertQuery_mysql.

Databaseverbinding

Een verbinding is een object van de klasse DatabaseConnection, dat uitbreidt op de PDO-klasse. Elke database waarmee Drupal verbinding maakt, heeft één afzonderlijke verbinding en een bijbehorend object. Dit verbindingsobject kan een subklasse zijn van de algemene klasse, afhankelijk van de driver.

Om toegang te krijgen tot een verbindingsobject gebruik je:

<?php
$conn = Database::getConnection($target, $key);
?>

Om toegang te krijgen tot de huidige actieve verbinding:

<?php
$conn = Database::getConnection();
?>

Hiermee krijg je toegang tot de actieve databaseverbinding.

In de meeste gevallen hoef je niet rechtstreeks met het verbindingsobject te werken — de functionele hulpfuncties van Drupal regelen dit voor je. De enige uitzondering is wanneer je complexe query’s tussen meerdere databases moet uitvoeren zonder de actieve verbinding te wijzigen.

Om de actieve verbinding handmatig in te stellen, gebruik je:

<?php
db_set_active($key);
?>

Databasequery’s

Een query is een SQL-instructie die via de databaseverbinding wordt uitgevoerd. De Drupal DB API ondersteunt zes soorten query’s: Static (statisch), Dynamic (dynamisch), Insert (invoegen), Update (bijwerken), Delete (verwijderen) en Merge (samenvoegen). Sommige query’s kunnen als gewone SQL-strings worden geschreven, terwijl andere gebruikmaken van de objectgeoriënteerde query builder. Een query-object verwijst naar deze query builder om een bepaald type query aan te maken.

Query schrijven

Een query wordt aangemaakt als een SELECT-instructie. Dit is altijd een object van het type DatabaseStatement of een subklasse daarvan. DatabaseStatement breidt de standaard PDOStatement-klasse uit.

Drupal gebruikt prepared statements voor alle query’s. Een prepared statement is een sjabloon voor een query waarin de waarden pas bij uitvoering worden ingevoegd. Dit is vergelijkbaar met hoe PDO werkt: eerst wordt een statement voorbereid en vervolgens worden bij elke uitvoering de waarden ingevoegd. Dit statement kan meerdere keren opnieuw worden gebruikt. In feite zijn “statement” en “resultaat” synoniemen zodra de query wordt uitgevoerd.

Drupal stelt deze prepared statements niet direct bloot aan de ontwikkelaar. In plaats daarvan gebruik je het queryobject om je SQL-instructie samen te stellen en uit te voeren via de API.