PDO::prepare
(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)
PDO::prepare —
Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
Beschreibung
Für jeden Wert, der beim Aufruf von
PDOStatement::execute() an die Anweisung übergeben
werden soll, muss ein eindeutiger Platzhalter angegeben werden. Ein
benannter Platzhalter darf nur dann mehrfach verwendet werden, wenn der
Emulationsmodus aktiviert ist.
Hinweis:
Die Platzhalter für die Parameter können nur ein vollständiges
Datenliteral darstellen. Es ist nicht möglich, einen Teil eines Literals,
ein Schlüsselwort, einen Bezeichner oder einen beliebigen Teil einer
Abfrage an einen Parameter zu binden. So können zum Beispiel in einer
IN()-Klausel einer SQL-Anweisung nicht mehrere Werte an einen einzigen
Parameter gebunden werden.
Mittels PDO::prepare() und
PDOStatement::execute() kann der Treiber bei
Anweisungen, die mehrfach mit unterschiedlichen Parameterwerten ausgeführt
werden, die Leistung einer Anwendung optimieren, indem er die
Zwischenspeicherung des Abfrageplans und der Metainformationen auf Client-
und/oder Serverseite aushandelt. Außerdem trägt dies dazu bei, Angriffe
durch SQL-Injection zu verhindern, weil die Parameter nicht mehr manuell
maskiert und in Anführungszeichen gesetzt werden müssen.
Bei Treibern, die diese nicht unterstützen, emuliert PDO vorbereitete
Anweisungen/gebundene Parameter und kann außerdem benannte oder mit
Fragezeichen versehene Parametermarkierungen in eine geeignetere Form
umwandeln, wenn der Treiber zwar die eine, nicht aber die andere Form
unterstützt.
Hinweis:
Der Parser, der für emulierte vorbereitete Anweisungen verwendet wird und
die benannten oder durch Fragezeichen angegebenen Parameter umschreibt,
unterstützt die nicht standardmäßige Maskierung einfacher und doppelter
Anführungszeichen durch Backslashes. Dies hat zur Folge, dass
abschließende Anführungszeichen, denen ein Backslash unmittelbar
vorausgeht, nicht als solche erkannt werden, was dazu führen kann, dass
Parameter falsch erkannt werden und die vorbereitete Anweisung bei ihrer
Ausführung fehlschlägt. Um dies zu umgehen, sollten für solche
SQL-Abfragen keine emulierten vorbereiteten Anweisungen verwendet werden.
Außerdem sollte ein vom Treiber nativ unterstützter Parameterstil
verwendet werden, um ein Umschreiben der Parameter zu vermeiden.
Seit PHP 7.4.0 können Fragezeichen durch Verdoppeln maskiert werden. Das
bedeutet, dass die Zeichenkette ?? beim Senden der
Abfrage an die Datenbank in ? übersetzt wird.
Parameter-Liste
query-
Dies muss eine für den jeweiligen Datenbankserver gültige Vorlage für
eine SQL-Anweisung sein.
options-
Dieses Array enthält ein oder mehrere Schlüssel=>Wert-Paare, um die
Werte der Attribute des von dieser Methode zurückgegebenen
PDOStatement-Objekts zu setzen. Am häufigsten wird dies verwendet, um
den Wert von PDO::ATTR_CURSOR für einen
scrollbaren Cursor auf PDO::CURSOR_SCROLL zu
setzen. Einige Treiber haben treiberspezifische Optionen, die während
der Vorbereitung gesetzt werden können.
Rückgabewerte
Wenn der Datenbankserver die Anweisung erfolgreich vorbereitet hat, gibt
PDO::prepare() ein
PDOStatement-Objekt zurück. Schlägt die Vorbereitung
fehl, gibt PDO::prepare() false zurück oder löst
eine PDOException aus (abhängig von der
Fehlerbehandlung).
Hinweis:
Da emulierte vorbereitete Anweisungen nicht mit dem Datenbankserver
kommunizieren, überprüft PDO::prepare() die
Anweisung nicht.
Beispiele
Beispiel #1 Vorlage für eine SQL-Anweisung mit benannten Parametern
<?php
/* Ausführen einer vorbereiteten Anweisung durch Übergabe eines Arrays von Werten */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
$sth->execute(['calories' => 150, 'colour' => 'red']);
$red = $sth->fetchAll();
/* Den Array-Schlüsseln kann auch ein Doppelpunkt ":" vorangestellt werden (optional) */
$sth->execute([':calories' => 175, ':colour' => 'yellow']);
$yellow = $sth->fetchAll();
?>
Beispiel #2 Vorlage für eine SQL-Anweisung mit Fragezeichen als Platzhalter
<?php
/* Ausführen einer vorbereiteten Anweisung durch Übergabe eines Arrays von Werten */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute([150, 'red']);
$red = $sth->fetchAll();
$sth->execute([175, 'yellow']);
$yellow = $sth->fetchAll();
?>
Beispiel #3 Vorlage für eine SQL-Anweisung mit maskierten Fragezeichen
<?php
/* Hinweis: dies ist nur bei PostgreSQL-Datenbanken möglich */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>
