Signatur
Beschreibung
dba_replace schreibt einen Schlüssel-Wert-Paar in eine geöffnete DBA-Datenbank. Existiert der angegebene Schlüssel bereits, wird sein Wert überschrieben. Existiert er noch nicht, wird ein neuer Eintrag angelegt. Die Funktion kombiniert damit das Verhalten von dba_insert und einem manuellen Update in einem einzigen Aufruf.
DBA (Database Abstraction Layer) ist PHPs Schnittstelle zu dateibasierten Schlüssel-Wert-Datenbanken wie GDBM, NDBM, DB4 oder CDB. Die Datenbank muss zuvor mit dba_open oder dba_popen im Schreib- oder Lese-Schreib-Modus geöffnet worden sein, andernfalls schlägt der Aufruf fehl.
Die Funktion eignet sich besonders für Szenarien, in denen nicht im Voraus bekannt ist, ob ein Schlüssel bereits vorhanden ist, und ein bedingtes Prüfen mit dba_exists vor dem Schreiben vermieden werden soll. Sie ist damit effizienter als eine separate Existenzprüfung gefolgt von dba_insert oder dba_replace.
Ab PHP 8.4 wird das Datenbankhandle als Objekt vom Typ Dba\Connection übergeben; in älteren PHP-Versionen handelt es sich um eine resource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | string | Der Schlüssel des Eintrags, der ersetzt oder neu angelegt werden soll. | |
| $value Pflicht | string | Der Wert, der dem Schlüssel zugeordnet werden soll. | |
| $dba Pflicht | Dba\Connection | Das Datenbankhandle, das von dba_open oder dba_popen zurückgegeben wurde. Die Datenbank muss im Schreibmodus geöffnet sein (w, wd usw.). |
Rückgabewert
true zurück, wenn der Eintrag erfolgreich ersetzt oder eingefügt wurde. Gibt false zurück, wenn ein Fehler aufgetreten ist, z. B. wenn die Datenbank nicht beschreibbar ist oder das Handle ungültig ist.Beispiele
Eintrag einfügen oder aktualisieren
<?php
// Datenbank im Lese-Schreib-Modus öffnen (erstellen wenn nicht vorhanden)
$db = dba_open('/tmp/meine_daten.db', 'wd', 'gdbm');
if ($db === false) {
die('Datenbank konnte nicht geöffnet werden.');
}
// Eintrag einfügen oder überschreiben
$erfolg = dba_replace('benutzername', 'max.mustermann', $db);
if ($erfolg) {
echo 'Eintrag erfolgreich gespeichert.' . PHP_EOL;
} else {
echo 'Fehler beim Speichern.' . PHP_EOL;
}
// Wert auslesen zur Überprüfung
$wert = dba_fetch('benutzername', $db);
echo 'Gespeicherter Wert: ' . $wert . PHP_EOL;
dba_close($db);Vorhandenen Eintrag überschreiben
<?php
$db = dba_open('/tmp/einstellungen.db', 'wd', 'gdbm');
if ($db === false) {
die('Datenbank konnte nicht geöffnet werden.');
}
// Ersten Wert setzen
dba_replace('sprache', 'de', $db);
echo 'Vor Aktualisierung: ' . dba_fetch('sprache', $db) . PHP_EOL;
// Wert mit dba_replace überschreiben (kein dba_exists nötig)
dba_replace('sprache', 'en', $db);
echo 'Nach Aktualisierung: ' . dba_fetch('sprache', $db) . PHP_EOL;
dba_close($db);// Wichtig · Fallstricke
Öffnungsmodus beachten: Die Datenbank muss zwingend in einem beschreibbaren Modus geöffnet worden sein (z. B. w, wd, n). Bei einem Handle, das nur im Lesemodus (r) geöffnet wurde, gibt dba_replace false zurück.
Nebenläufigkeit: DBA-Dateien unterstützen kein echtes paralleles Schreiben. Bei gleichzeitigem Zugriff aus mehreren Prozessen sollten DBA-Locking-Mechanismen oder externe Sperren verwendet werden, um Datenverlust zu vermeiden.
Unterschied zu dba_insert: dba_insert schlägt fehl, wenn der Schlüssel bereits existiert, während dba_replace in diesem Fall den vorhandenen Wert überschreibt. dba_replace ist daher für Upsert-Szenarien die bessere Wahl.