pg_lo_write — Funktion · PHP-Referenz

Signatur

pg_lo_write(PgSql\Lob $lob, string $data, int $len = ?): int|false

Beschreibung

pg_lo_write() schreibt einen String in ein zuvor mit pg_lo_open() geöffnetes Large Object (LO) in einer PostgreSQL-Datenbank. Die Funktion schreibt ab der aktuellen Position des internen Zeigers des Large Objects und gibt die Anzahl der tatsächlich geschriebenen Bytes zurück.

Large Objects in PostgreSQL ermöglichen die Speicherung großer Binär- oder Textdaten (z. B. Bilder, Videos, Dokumente) direkt in der Datenbank. Sie werden über einen OID (Object Identifier) referenziert und müssen innerhalb einer Transaktion geöffnet und bearbeitet werden.

Der optionale Parameter len begrenzt die Anzahl der zu schreibenden Bytes auf maximal diesen Wert. Wird er weggelassen oder ist er größer als strlen($data), wird der gesamte String geschrieben. Vor dem Aufruf muss das Large Object mit Schreibrechten geöffnet worden sein (Modus INV_WRITE).

Wichtig: Alle Large-Object-Operationen müssen innerhalb einer Transaktion stattfinden. Ohne eine aktive Transaktion schlägt die Operation fehl. Verwende pg_query($conn, 'BEGIN') bzw. pg_query($conn, 'COMMIT') zur Transaktionssteuerung.

Parameter

Name	Typ	Beschreibung
$lob Pflicht	PgSql\Lob	Ein Large-Object-Handle, das zuvor mit `pg_lo_open()` geöffnet wurde.
$data Pflicht	string	Die zu schreibenden Daten als String. Kann beliebige Binär- oder Textdaten enthalten.
$len	int	Maximale Anzahl der zu schreibenden Bytes. Ist der Wert größer als die tatsächliche Länge von `data` oder wird er weggelassen, wird der gesamte String geschrieben.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Anzahl der tatsächlich geschriebenen Bytes als int zurück. Bei einem Fehler wird false zurückgegeben.

Beispiele

Dateiinhalt in ein PostgreSQL-Large-Object schreiben

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

// Transaktion starten – zwingend erforderlich für Large Objects
pg_query($conn, 'BEGIN');

// Neues Large Object anlegen
$oid = pg_lo_create($conn);

// Large Object zum Schreiben öffnen
$lob = pg_lo_open($conn, $oid, 'w');

if ($lob === false) {
    pg_query($conn, 'ROLLBACK');
    die('Large Object konnte nicht geöffnet werden.');
}

$data = 'Hallo, das sind Beispieldaten für ein Large Object!';
$geschrieben = pg_lo_write($lob, $data);

if ($geschrieben === false) {
    pg_query($conn, 'ROLLBACK');
    die('Fehler beim Schreiben in das Large Object.');
}

echo "Bytes geschrieben: $geschrieben\n";

pg_lo_close($lob);
pg_query($conn, 'COMMIT');

echo "OID des Large Objects: $oid\n";

pg_close($conn);
?>

Bytes geschrieben: 51 OID des Large Objects: 16384

Begrenztes Schreiben mit dem len-Parameter

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

pg_query($conn, 'BEGIN');

$oid = pg_lo_create($conn);
$lob = pg_lo_open($conn, $oid, 'w');

if ($lob === false) {
    pg_query($conn, 'ROLLBACK');
    die('Fehler beim Öffnen des Large Objects.');
}

$data = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

// Nur die ersten 10 Bytes schreiben
$geschrieben = pg_lo_write($lob, $data, 10);

echo "Bytes geschrieben: $geschrieben\n"; // Ausgabe: 10

pg_lo_close($lob);
pg_query($conn, 'COMMIT');
pg_close($conn);
?>

Bytes geschrieben: 10

// Wichtig · Fallstricke

Transaktion zwingend erforderlich: PostgreSQL Large Objects können nur innerhalb einer aktiven Transaktion verwendet werden. Vergisst man BEGIN vor dem Öffnen des Large Objects, schlägt jede Operation auf dem LO-Handle fehl.

Modus beachten: Das Large Object muss mit dem Schreibmodus ('w' oder 'rw') geöffnet worden sein. Ein nur zum Lesen geöffnetes Large Object kann nicht beschrieben werden.

Binärsicherheit: Die Funktion ist binärsicher und eignet sich auch zum Schreiben von Binärdaten wie Bildern oder komprimierten Dateien. Dennoch sollten beim Einlesen von Benutzerdaten stets Größenbeschränkungen gesetzt werden, um übermäßigen Speicherverbrauch zu vermeiden.

PHP 8.1+: Ab PHP 8.1 wird der Rückgabewert von pg_lo_open() als PgSql\Lob-Objekt statt als Ressource zurückgegeben.

Siehe auch

pg_lo_open pg_lo_read pg_lo_create pg_lo_close pg_lo_seek pg_lo_tell pg_lo_unlink pg_lo_import