Statische Anfragen

Die am häufigsten verwendeten SELECT-Abfragen in Drupal sind statische Abfragen, die die Methode query() des Datenbankverbindungsobjekts verwenden.
Statische Abfragen werden nahezu wortwörtlich an die Datenbank übergeben.

Beispiel:

$database = \Drupal::database();
$query = $database->query("SELECT id, example FROM {mytable}");
$result = $query->fetchAll();

Nur sehr einfache SELECT-Abfragen sollten die statische Methode query() verwenden. Für komplexere Abfragen, dynamische Abfrageerstellung oder Variabilität sollten Sie dynamische Abfragen nutzen.

Verwenden Sie diese Funktion nicht für einfache INSERT-, UPDATE- oder DELETE-Abfragen. Diese sollten über insert(), update() und delete() abgewickelt werden. Für komplexere DELETE-Abfragen über mehrere Tabellen siehe Komplexe DELETE-Abfragen.

Argumente

Die Methode query() des Datenbankverbindungsobjekts akzeptiert drei Argumente:

• $query: die auszuführende Abfrage. Verwenden Sie bei Bedarf Platzhalter und setzen Sie alle Tabellennamen in geschweifte Klammern.
• $args: ein Array von Werten für Platzhalter, die in der Abfrage ersetzt werden.
• $options: ein Array von Optionen zur Steuerung der Abfrageausführung (optional).

Tabellenpräfix

In statischen Abfragen müssen alle Tabellennamen in geschweifte Klammern {...} gesetzt werden.

Das Einrahmen der Tabellennamen in geschweifte Klammern kennzeichnet sie so, dass das Datenbanksystem bei Bedarf einen Präfix hinzufügen kann. Das Präfix ermöglicht es, mehrere Seiten aus einer Datenbank zu betreiben oder in manchen Fällen ausgewählte Tabellen zwischen Seiten zu teilen. Außerdem wird so verhindert, dass Daten vom Host der Seite in Tests gelangen.

Platzhalter

Platzhalter markieren Stellen, an denen Literale in die Abfrage eingesetzt werden. Durch Trennung vom eigentlichen SQL-Syntax ermöglichen wir der Datenbank, zwischen SQL-Befehlen und Benutzereingaben zu unterscheiden, was SQL-Injection-Angriffe verhindert.

$query = $database->query("SELECT id, example FROM {mytable} WHERE created > :created", [
  ':created' => REQUEST_TIME - 3600,
]);

Der obige Code wählt alle IDs und Beispiele aus mytable aus, die innerhalb der letzten Stunde (3600 Sekunden) erstellt wurden. Der Platzhalter :created wird zur Laufzeit durch den Wert REQUEST_TIME - 3600 ersetzt.

Eine Abfrage kann beliebig viele Platzhalter haben, diese müssen aber alle eindeutige Namen haben, auch wenn sie denselben Wert besitzen. Je nach Anwendungsfall kann das Platzhalter-Array inline angegeben werden (wie oben) oder vorher zusammengesetzt und übergeben werden. Die Reihenfolge der Elemente im Array ist egal.

Platzhalter, die mit "db_" beginnen, sind für die interne Verwendung reserviert und sollten nie explizit angegeben werden.

Beachten Sie, dass Platzhalter niemals escaped oder in Anführungszeichen gesetzt werden dürfen, egal welchen Typs sie sind. Da sie getrennt an den Datenbankserver übergeben werden, kann dieser SQL-Code und Wert unterscheiden.

// FALSCH (Anführungszeichen um den :type Platzhalter)
$result = $database->query("SELECT example FROM {mytable} WHERE type = ':type'", [
  ':type' => 'mytype',
]);

// RICHTIG (keine Anführungszeichen um den :type Platzhalter)
$result = $database->query("SELECT example FROM {mytable} WHERE type = :type", [
  ':type' => 'mytype',
]);

Platzhalter dürfen nicht für Spalten- oder Tabellennamen verwendet werden. Wenn diese aus unsicheren Eingaben stammen, sollten sie mit $database->escapeTable() bereinigt werden.

Platzhalter-Arrays

Die Drupal-Datenbankebene bietet eine erweiterte Funktion für Platzhalter. Wenn der Wert eines Platzhalters ein Array ist, wird dieser automatisch in eine kommaseparierte Liste für den entsprechenden Platzhalter aufgelöst. Entwickler müssen so nicht die Anzahl der Platzhalter zählen.

Das folgende Beispiel verdeutlicht dieses Verhalten:

$result = $database->query("SELECT * FROM {mytable} WHERE id IN (:ids[])", [':ids[]' => [13, 42, 144]]);

Die folgenden beiden Anweisungen sind äquivalent zu der obigen:

$result = $database->query("SELECT * FROM {mytable} WHERE id IN (:ids_1, :ids_2, :ids_3)", [
  ':ids_1' => 13, 
  ':ids_2' => 42, 
  ':ids_3' => 144,
]);

$result = $database->query("SELECT * FROM {mytable} WHERE id IN (13, 42, 144)");

Abfrageoptionen

Der dritte Parameter der query()-Methode des Datenbankverbindungsobjekts ist ein Array von Optionen, die das Verhalten der Abfrage bestimmen. Üblicherweise gibt es nur zwei Direktiven, die von den meisten Abfragen genutzt werden. Andere Werte sind überwiegend für interne Verwendung gedacht.

Der Schlüssel „target“ gibt an, welches Ziel verwendet werden soll. Wird kein Wert angegeben, ist der Standardwert „default“. Derzeit ist der einzige andere gültige Wert „replica“, um anzugeben, dass die Abfrage auf dem Replikationsserver ausgeführt werden soll, falls vorhanden.

Der Schlüssel „fetch“ gibt an, wie die aus der Abfrage zurückgegebenen Datensätze abgerufen werden sollen. Gültige Werte sind: PDO::FETCH_OBJ, PDO::FETCH_ASSOC, PDO::FETCH_NUM, PDO::FETCH_BOTH oder ein String, der einen Klassennamen repräsentiert. Wird ein String angegeben, wird jeder Datensatz als ein neues Objekt dieser Klasse zurückgegeben. Das Verhalten der anderen Werte entspricht der PDO-Dokumentation und liefert Daten als stdClass-Objekt, assoziatives Array, numerisches Array oder beides. Siehe http://php.net/manual/en/pdostatement.fetch.php. Standard ist PDO::FETCH_OBJ, was für Konsistenz empfohlen wird, es sei denn, es gibt einen besonderen Grund anders zu handeln.

Im folgenden Beispiel wird die Abfrage auf dem Replikationsserver ausgeführt, falls verfügbar, und die Datensätze werden als assoziatives Array zurückgegeben.

$result = $database->query("SELECT id, example FROM {mytable}", [], [
  'target' => 'replica',
  'fetch' => PDO::FETCH_ASSOC,
]);

Das durch query() zurückgegebene Ergebnisobjekt kann verwendet werden, um jede zurückgegebene Zeile und dann jede Spalte abzurufen. Im folgenden Beispiel enthält die Variable $result alle zurückgegebenen Zeilen, die einzeln mit fetchAssoc() in $row geladen werden:

$sql = "SELECT name, quantity FROM goods WHERE vid = :vid";
$result = $database->query($sql, [':vid' => $vid]);
if ($result) {
  while ($row = $result->fetchAssoc()) {
    // Mach etwas mit:
    // $row['name']
    // $row['quantity']
  }
}

Komplexe DELETE-Abfragen

Die Verwendung einer statischen Abfrage ist eine einfache und kompakte Möglichkeit, eine Löschabfrage auszudrücken, die das Löschen aus mehreren Tabellen in einem Ausdruck umfasst.

Beispiel:

$database = \Drupal::database();
$database->query("DELETE {table1}, {table2} FROM {table1} INNER JOIN {table2} ON {table1}.id = {table2}.id WHERE {table1}.id=:recno", [":recno" => 2]);

(Löscht eine Zeile sowohl aus Tabelle1 als auch aus Tabelle2)