pg_escape_literal — Funktion · PHP-Referenz

Signatur

pg_escape_literal(PgSql\Connection $connection, string $data): string|false

Beschreibung

pg_escape_literal() maskiert einen String so, dass er sicher als Literalwert in einer PostgreSQL-SQL-Anweisung verwendet werden kann. Im Gegensatz zu pg_escape_string() fügt diese Funktion die einfachen Anführungszeichen ('...') rund um den Wert automatisch hinzu und berücksichtigt dabei den aktuellen Zeichensatz der Datenbankverbindung.

Die Funktion ist die empfohlene Methode zum Maskieren von Zeichenketten, wenn Prepared Statements nicht verwendet werden. Sie ist sicherer als addslashes() oder manuelle Zeichenersetzungen, da sie intern die PostgreSQL-eigene Escape-Funktion PQescapeLiteral nutzt und somit verbindungsspezifische Zeichensatz-Eigenheiten korrekt behandelt.

Soll ein Bezeichner wie ein Tabellenname oder ein Spaltenname maskiert werden, ist stattdessen pg_escape_identifier() zu verwenden. Für Bytea-Felder (Binärdaten) dient pg_escape_bytea().

Wann immer möglich sollten jedoch parametrisierte Abfragen mit pg_query_params() bevorzugt werden, da sie strukturell sicherer gegenüber SQL-Injection sind.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird. Der Zeichensatz dieser Verbindung wird beim Maskieren berücksichtigt.
$data Pflicht	string		Der zu maskierende Zeichenkettenwert, der anschließend in eine SQL-Abfrage eingebettet werden soll.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den maskierten String zurück, der bereits von einfachen Anführungszeichen umschlossen ist und direkt in eine SQL-Abfrage eingefügt werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

Einfache Abfrage mit maskiertem Benutzernamen

<?php
$conn = pg_connect("host=localhost dbname=testdb user=postgres password=secret");
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

$benutzername = "O'Brien"; // Enthält ein einfaches Anführungszeichen
$escaped = pg_escape_literal($conn, $benutzername);

// $escaped ist jetzt: 'O''Brien' (inkl. der äußeren Anführungszeichen)
$sql = "SELECT * FROM benutzer WHERE name = " . $escaped;
echo $sql;
// Ausgabe: SELECT * FROM benutzer WHERE name = 'O''Brien'

$result = pg_query($conn, $sql);
pg_close($conn);

SELECT * FROM benutzer WHERE name = 'O''Brien'

Vergleich mit pg_query_params als sichere Alternative

<?php
$conn = pg_connect("host=localhost dbname=testdb user=postgres password=secret");
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

$suchbegriff = "'; DROP TABLE produkte; --";

// Sichere Variante mit pg_escape_literal:
$escaped = pg_escape_literal($conn, $suchbegriff);
$sql = "SELECT * FROM produkte WHERE bezeichnung = " . $escaped;
echo "Maskierte Abfrage: " . $sql . "\n";

// Noch sicherere Variante mit Prepared Statement:
$result = pg_query_params($conn, 'SELECT * FROM produkte WHERE bezeichnung = $1', [$suchbegriff]);

pg_close($conn);

Maskierte Abfrage: SELECT * FROM produkte WHERE bezeichnung = '''; DROP TABLE produkte; --'

// Wichtig · Fallstricke

Sicherheitshinweis: Obwohl pg_escape_literal() sicherer als einfache String-Ersetzungen ist, bleibt die Verwendung von pg_query_params() mit Platzhaltern ($1, $2, …) die empfohlene Praxis, da parametrisierte Abfragen strukturell keine SQL-Injection ermöglichen.

Achtung bei Spaltennamen und Tabellennamen: pg_escape_literal() darf nicht für SQL-Bezeichner (Tabellen- oder Spaltennamen) verwendet werden. Dafür ist pg_escape_identifier() vorgesehen, das doppelte Anführungszeichen verwendet.

Ab PHP 8.1 wird der Typ der Verbindung als PgSql\Connection-Objekt übergeben; in früheren Versionen war es eine PHP-Ressource vom Typ resource.

Siehe auch

pg_escape_string pg_escape_identifier pg_escape_bytea pg_query_params pg_query pg_connect