(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
Bereitet eine SQL-Anweisung vor, die von der Methode PDOStatement::execute() ausgeführt werden soll. Die Vorlage für eine Anweisung kann null oder mehr benannte (:name) oder mit Fragezeichen (?) versehene Platzhalter für Parameter enthalten, die bei der Ausführung der Anweisung durch reale Werte ersetzt werden. Benannte und Fragezeichen-Parameter dürfen nicht gleichzeitig in derselben Anweisungsvorlage verwendet werden, sondern nur eine der beiden Varianten. Diese Parameter werden verwendet, um die Benutzereingaben zu binden. Benutzerangaben sollten niemals direkt in die Abfrage aufgenommen werden.
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.
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.
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.
Gibt einen Fehler der Stufe E_WARNING
aus, wenn das Attribut PDO::ATTR_ERRMODE
auf PDO::ERRMODE_WARNING
gesetzt ist.
Löst eine PDOException aus, wenn das Attribut PDO::ATTR_ERRMODE
auf PDO::ERRMODE_EXCEPTION
gesetzt ist.
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();
?>