Signatur
Beschreibung
pg_escape_bytea() maskiert einen beliebigen PHP-String so, dass er sicher als Literal in einem PostgreSQL-bytea-Datentyp verwendet werden kann. Der Typ bytea dient in PostgreSQL zur Speicherung beliebiger Binärdaten (z. B. Bilder, Dateien, komprimierte Daten). Da bytea-Felder Byte-Werte enthalten können, die in SQL-Strings gefährlich oder ungültig wären (wie Null-Bytes oder Backslashes), ist eine spezielle Maskierung erforderlich, die sich von der gewöhnlichen String-Maskierung unterscheidet.
Die Funktion akzeptiert wahlweise eine Verbindungs-Ressource als erstes Argument. Wird eine Verbindung übergeben, passt PHP die Escape-Methode automatisch an die Server-Version und Konfiguration (insbesondere standard_conforming_strings) an. Ohne Verbindung wird die ältere Escape-Konvention verwendet, was in modernen PostgreSQL-Installationen zu Problemen führen kann.
Bei vorbereiteten Anweisungen (pg_query_params()) ist keine manuelle Maskierung nötig — dort übergibt man Binärdaten direkt als Parameter. pg_escape_bytea() wird typischerweise eingesetzt, wenn Binärdaten direkt in einen SQL-String interpoliert werden müssen, also bei dynamisch aufgebauten Abfragen ohne Prepared Statements.
Der Rückgabewert enthält den maskierten String inklusive der PostgreSQL-typischen Backslash-Escape-Sequenzen. Er ist für die Verwendung innerhalb von einfachen Anführungszeichen in einer SQL-Abfrage vorgesehen. Zum Umkehren (beim Lesen) dient pg_unescape_bytea().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $connection_or_string Pflicht | PgSql\Connection|string | Entweder eine aktive PostgreSQL-Verbindung (Instanz von PgSql\Connection, früher eine Ressource) oder — wenn kein Verbindungsargument übergeben wird — der zu maskierende String. Wird eine Verbindung übergeben, passt sich die Maskierung an die Server-Einstellungen an. |
|
| $string | string | Der zu maskierende Binär-String. Wird nur angegeben, wenn das erste Argument eine Verbindung ist. |
Rückgabewert
bytea-Literal in einer PostgreSQL-SQL-Abfrage verwendet werden kann. Der String enthält PostgreSQL-Backslash-Escape-Sequenzen und muss innerhalb von einfachen Anführungszeichen in der SQL-Abfrage eingebettet werden.Beispiele
Binärdatei in PostgreSQL bytea-Feld speichern
<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');
if (!$conn) {
die('Verbindung fehlgeschlagen');
}
// Binärdaten einlesen (z. B. ein Bild)
$binaryData = file_get_contents('/pfad/zur/datei.png');
// Binärdaten für PostgreSQL bytea maskieren
$escaped = pg_escape_bytea($conn, $binaryData);
// SQL-Abfrage mit maskierten Daten
$sql = "INSERT INTO bilder (name, daten) VALUES ('logo.png', '" . $escaped . "')";
$result = pg_query($conn, $sql);
if ($result) {
echo 'Bild erfolgreich gespeichert.';
} else {
echo 'Fehler beim Speichern: ' . pg_last_error($conn);
}
pg_close($conn);Binärdaten lesen und zurück konvertieren mit pg_unescape_bytea
<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=secret');
// Komprimierte Binärdaten vorbereiten und speichern
$originalData = gzcompress('Hallo, das sind komprimierte Daten!');
$escaped = pg_escape_bytea($conn, $originalData);
pg_query($conn, "INSERT INTO blobs (inhalt) VALUES ('" . $escaped . "')");
// Daten wieder lesen
$result = pg_query($conn, 'SELECT inhalt FROM blobs ORDER BY id DESC LIMIT 1');
$row = pg_fetch_assoc($result);
// pg_unescape_bytea zum Umkehren der Maskierung verwenden
$wiederhergestellt = pg_unescape_bytea($row['inhalt']);
$klartext = gzuncompress($wiederhergestellt);
echo $klartext;// Wichtig · Fallstricke
Sicherheitshinweis: Obwohl pg_escape_bytea() Binärdaten sicher maskiert, ist die Verwendung von Prepared Statements via pg_query_params() generell vorzuziehen. Dabei werden Binärdaten als Parameter übergeben und es ist keine manuelle Maskierung erforderlich, was SQL-Injection grundsätzlich ausschließt.
Verbindung immer übergeben: Seit PHP 5.2 sollte immer eine aktive Verbindung als erstes Argument übergeben werden, damit die Maskierung korrekt an die PostgreSQL-Serverversion und die Einstellung standard_conforming_strings angepasst wird. Andernfalls kann es zu Fehler bei der Datenbankabfrage kommen.
Rückgabe-Maskierung: Beim Lesen von bytea-Werten aus der Datenbank gibt PostgreSQL die Escape-Sequenzen zurück. Um die ursprünglichen Binärdaten wiederherzustellen, muss pg_unescape_bytea() auf den Rückgabewert angewendet werden.
Ab PHP 8.1 ist die Verwendung von PgSql\Connection-Objekten anstelle der alten resource-Typen erforderlich; die alte Ressource-API ist als deprecated markiert.