pg_escape_string — Funktion · PHP-Referenz

Signatur

pg_escape_string(PgSql\Connection|string $connection_or_string, string $string = ?): string

Beschreibung

pg_escape_string() maskiert einen String so, dass er sicher als Literalwert in eine PostgreSQL-SQL-Abfrage eingebettet werden kann. Dabei werden gefährliche Zeichen wie einfache Anführungszeichen (') und Backslashes (\) korrekt escapt, sodass sie nicht als SQL-Steuerzeichen interpretiert werden.

Die Funktion akzeptiert optional eine Datenbankverbindung als erstes Argument. Dies ist empfohlen, da PostgreSQL je nach Verbindungszeichensatz unterschiedliche Escape-Regeln anwenden muss. Wird keine Verbindung übergeben, wird die zuletzt geöffnete Verbindung verwendet.

Im Gegensatz zu pg_escape_bytea() ist diese Funktion für reguläre Text-Werte gedacht und eignet sich nicht für binäre Daten (z. B. Bilddaten). Für Binärdaten sollte stattdessen pg_escape_bytea() verwendet werden.

Hinweis: Die Verwendung von vorbereiteten Anweisungen (pg_query_params()) wird generell bevorzugt, da sie das Escaping komplett überflüssig machen und robuster gegen SQL-Injection sind.

Parameter

Name	Typ	Default	Beschreibung
$connection_or_string Pflicht	PgSql\Connection\|string		Entweder eine aktive PostgreSQL-Verbindungsinstanz (`PgSql\Connection`), oder — bei Weglassen des zweiten Parameters — direkt der zu maskierende String. Wird eine Verbindung übergeben, richtet sich das Escaping nach dem Zeichensatz dieser Verbindung.
$string	string		Der zu maskierende String. Nur erforderlich, wenn als erstes Argument eine Datenbankverbindung übergeben wurde.

Rückgabewert

Typ

string

Beschreibung

Gibt den maskierten String zurück, der sicher als Stringliteral in eine SQL-Abfrage eingebettet werden kann. Die zurückgegebene Zeichenkette enthält noch keine umschließenden Anführungszeichen — diese müssen beim Einbetten in die Abfrage manuell hinzugefügt werden.

Beispiele

Einfaches Escaping eines Benutzer-Inputs

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

$benutzereingabe = "O'Brien"; // enthält ein einfaches Anführungszeichen
$escaped = pg_escape_string($conn, $benutzereingabe);

$sql = "SELECT * FROM kunden WHERE nachname = '" . $escaped . "'";
echo $sql;
// Ausgabe: SELECT * FROM kunden WHERE nachname = 'O\'Brien'

$result = pg_query($conn, $sql);
?>

SELECT * FROM kunden WHERE nachname = 'O\'Brien'

Verwendung ohne explizite Verbindungsangabe

<?php
// Zuletzt geöffnete Verbindung wird automatisch verwendet
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

$suchbegriff = "Test'; DROP TABLE kunden; --";
$escaped = pg_escape_string($suchbegriff); // Verbindung wird weggelassen

$sql = "SELECT * FROM produkte WHERE bezeichnung = '" . $escaped . "'";
echo $sql;
?>

SELECT * FROM produkte WHERE bezeichnung = 'Test''; DROP TABLE kunden; --'

Empfohlene Alternative: Vorbereitete Anweisung

<?php
// Besser als pg_escape_string: pg_query_params() verwenden
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

$benutzereingabe = "O'Brien";

// Kein manuelles Escaping notwendig
$result = pg_query_params($conn, 'SELECT * FROM kunden WHERE nachname = $1', [$benutzereingabe]);

while ($row = pg_fetch_assoc($result)) {
    echo $row['nachname'] . PHP_EOL;
}
?>

// Wichtig · Fallstricke

Sicherheitshinweis: pg_escape_string() bietet grundlegenden Schutz vor SQL-Injection, ist jedoch fehleranfälliger als vorbereitete Anweisungen. Es wird dringend empfohlen, stattdessen pg_query_params() oder PDO mit Prepared Statements zu verwenden, da diese das Escaping vollständig kapseln.

Zeichensatz-Problematik: Ohne Verbindungsangabe kann die Funktion den Datenbankzeichensatz nicht kennen. Bei Multibyte-Zeichensätzen wie SJIS (Shift-JIS) können in seltenen Fällen Escape-Lücken entstehen. Immer die aktive Verbindung übergeben!

Binärdaten: Diese Funktion ist nicht für binäre Daten geeignet. Für das Escaping von Binärdaten (z. B. für bytea-Felder) muss pg_escape_bytea() verwendet werden.

Ab PHP 8.1 ist der Rückgabetyp der Verbindungsparameter von resource auf PgSql\Connection geändert worden.

Siehe auch

pg_escape_bytea pg_escape_identifier pg_query_params pg_query pg_connect