pg_convert — Funktion · PHP-Referenz

Signatur

pg_convert(PgSql\Connection $connection, string $table_name, array $values, int $flags = 0): array|false

Beschreibung

pg_convert() nimmt ein assoziatives Array mit Spaltennamen als Schlüssel und zu speichernden Werten und konvertiert diese anhand der Typdefinitionen der angegebenen Tabelle in gültige, SQL-sichere Werte für PostgreSQL. Die Funktion prüft dabei, ob die übergebenen Werte mit den Spaltentypen der Tabelle kompatibel sind.

Dies ist besonders nützlich in Kombination mit pg_insert(), pg_update() oder pg_select(), die intern ebenfalls pg_convert() verwenden. Man kann die Funktion aber auch separat einsetzen, um vorbereitete Werte zu erhalten, bevor man sie manuell in eine SQL-Abfrage einbaut.

Das Rückgabe-Array enthält die Werte in einer für PostgreSQL geeigneten, gequoteten Form. Zum Beispiel werden Strings mit einfachen Anführungszeichen umschlossen und NULL-Werte als SQL-NULL dargestellt. Boolesche Werte werden entsprechend umgewandelt.

Der optionale Parameter flags erlaubt die Steuerung des Konvertierungsverhaltens, z. B. durch PGSQL_CONV_FORCE_NULL, um leere Strings als NULL zu behandeln, oder PGSQL_CONV_IGNORE_DEFAULT und PGSQL_CONV_IGNORE_NOT_NULL.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, die mit `pg_connect()` oder `pg_pconnect()` geöffnet wurde.
$table_name Pflicht	string		Der Name der Tabelle, deren Spaltendefinitionen zur Typvalidierung und -konvertierung der übergebenen Werte verwendet werden.
$values Pflicht	array		Ein assoziatives Array, bei dem die Schlüssel Spaltennamen der Tabelle entsprechen und die Werte die zu konvertierenden Eingabewerte sind.
$flags	int	0	Optionale Steuerflags. Mögliche Werte: `PGSQL_CONV_IGNORE_DEFAULT` (Standardwerte ignorieren), `PGSQL_CONV_FORCE_NULL` (leere Strings als `NULL` behandeln), `PGSQL_CONV_IGNORE_NOT_NULL` (`NOT NULL`-Einschränkungen ignorieren). Flags können mit `\|` kombiniert werden.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein assoziatives Array mit den konvertierten, SQL-sicheren Werten zurück. Bei einem Fehler (z. B. ungültige Spaltenname, Typinkompatibilität) wird false zurückgegeben.

Beispiele

Einfache Konvertierung vor einem manuellen INSERT

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

// Angenommen, die Tabelle 'users' hat die Spalten: id (serial), name (varchar), active (boolean), score (float)
$data = [
    'name'   => "O'Brien",
    'active' => true,
    'score'  => 9.5,
];

$converted = pg_convert($conn, 'users', $data);

if ($converted === false) {
    echo "Konvertierung fehlgeschlagen.\n";
} else {
    print_r($converted);
    // Beispielausgabe:
    // Array
    // (
    //     [name]   => 'O\'Brien'
    //     [active] => 't'
    //     [score]  => '9.5'
    // )
}

pg_close($conn);

Array ( [name] => 'O\'Brien' [active] => 't' [score] => '9.5' )

Verwendung mit PGSQL_CONV_FORCE_NULL für leere Strings

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

// Leere Strings sollen als NULL in die Datenbank geschrieben werden
$data = [
    'name'  => 'Alice',
    'score' => '',   // soll als NULL behandelt werden
];

$converted = pg_convert($conn, 'users', $data, PGSQL_CONV_FORCE_NULL);

if ($converted !== false) {
    print_r($converted);
    // score wird als NULL dargestellt
}

pg_close($conn);

Array ( [name] => 'Alice' [score] => NULL )

// Wichtig · Fallstricke

Sicherheitshinweis: Obwohl pg_convert() die Werte für die Verwendung in SQL-Anweisungen aufbereitet, sollte man für sicherheitskritische Anwendungen bevorzugt parametrisierte Abfragen mit pg_query_params() verwenden, da diese SQL-Injection strukturell ausschließen.

Typ-Validierung: Die Funktion prüft die Werte gegen die tatsächlichen Spaltentypen der Tabelle in der Datenbank. Ist ein Wert nicht kompatibel (z. B. ein String für eine Integer-Spalte), gibt die Funktion false zurück und erzeugt einen Fehler. Daher muss die Tabelle in der Datenbank existieren.

PHP 8.1: Ab PHP 8.1 ist der Parameter connection vom Typ PgSql\Connection statt der älteren Ressource. In älteren Versionen war der Typ resource.

Siehe auch

pg_insert pg_update pg_select pg_query_params pg_escape_string pg_connect