Signatur
Beschreibung
dba_insert schreibt einen neuen Datensatz mit dem angegebenen Schlüssel und Wert in eine DBA-Datenbank (Database Abstraction Layer). Wichtig: Existiert der Schlüssel bereits, schlägt die Funktion fehl und gibt false zurück, ohne den vorhandenen Wert zu überschreiben. Um einen bestehenden Eintrag zu aktualisieren oder neu anzulegen, sollte stattdessen dba_replace verwendet werden.
DBA ist PHPs Schnittstelle zu einfachen dateibasierten Schlüssel-Wert-Datenbanken wie dbm, ndbm, gdbm, Berkeley DB oder cdb. Die Datenbank muss zuvor mit dba_open oder dba_popen im Schreibmodus (z. B. 'c', 'n' oder 'w') geöffnet worden sein.
Die Funktion eignet sich besonders dann, wenn sichergestellt werden soll, dass kein bereits vorhandener Datensatz unbeabsichtigt überschrieben wird – etwa beim erstmaligen Befüllen einer Datenbank oder beim Importieren von Datensätzen, bei denen Duplikate erkannt werden sollen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $key Pflicht | string | Der eindeutige Schlüssel des einzufügenden Eintrags. Existiert dieser Schlüssel bereits in der Datenbank, gibt die Funktion false zurück. |
|
| $value Pflicht | string | Der Wert, der dem Schlüssel zugeordnet und in der Datenbank gespeichert werden soll. | |
| $dba Pflicht | Dba\Connection|resource | Das DBA-Datenbankhandle, das von dba_open oder dba_popen zurückgegeben wurde. Ab PHP 8.4 ist dies ein Dba\Connection-Objekt, in älteren Versionen ein resource. |
Rückgabewert
true zurück, wenn der Eintrag erfolgreich eingefügt wurde. Gibt false zurück, wenn der Schlüssel bereits existiert oder ein Fehler aufgetreten ist.Beispiele
Einfaches Einfügen eines neuen Eintrags
<?php
// Datenbank im Erstellungs-/Schreibmodus öffnen
$db = dba_open('/tmp/testdb.db', 'c', 'gdbm');
if ($db === false) {
die('Datenbank konnte nicht geöffnet werden.');
}
// Neuen Eintrag einfügen
if (dba_insert('benutzername', 'max.mustermann', $db)) {
echo "Eintrag erfolgreich eingefügt.\n";
} else {
echo "Einfügen fehlgeschlagen (Schlüssel existiert möglicherweise bereits).\n";
}
dba_close($db);
?>Duplikat-Erkennung beim Einfügen
<?php
$db = dba_open('/tmp/userdb.db', 'c', 'gdbm');
if ($db === false) {
die('Datenbank konnte nicht geöffnet werden.');
}
$schluessel = 'user_42';
$wert = 'Anna Beispiel';
// Ersten Eintrag einfügen
if (dba_insert($schluessel, $wert, $db)) {
echo "Erster Eintrag gespeichert.\n";
} else {
echo "Erster Eintrag konnte nicht gespeichert werden.\n";
}
// Versuch, denselben Schlüssel erneut einzufügen
if (!dba_insert($schluessel, 'Anderer Name', $db)) {
echo "Einfügen fehlgeschlagen: Schlüssel '{$schluessel}' existiert bereits.\n";
// Vorhandenen Wert auslesen
echo 'Vorhandener Wert: ' . dba_fetch($schluessel, $db) . "\n";
}
dba_close($db);
?>// Wichtig · Fallstricke
Schreibmodus erforderlich: Die Datenbank muss mit einem Schreibmodus geöffnet sein ('c', 'n' oder 'w'). Bei einem reinen Lesemodus ('r') schlägt dba_insert fehl.
Kein Überschreiben: Im Gegensatz zu dba_replace überschreibt dba_insert niemals einen vorhandenen Schlüssel. Soll ein Eintrag angelegt oder aktualisiert werden, ist dba_replace die richtige Wahl.
Dateiberechtigungen: Bei dateibasierten DBA-Backends muss das PHP-Prozess-Konto Schreibrechte auf die Datenbankdatei und das übergeordnete Verzeichnis besitzen.
PHP 8.4: Ab PHP 8.4 wird das Datenbankhandle als Dba\Connection-Objekt statt als resource zurückgegeben. Der Code bleibt aber weitgehend kompatibel.