fbird_gen_id — Funktion · PHP-Referenz

Signatur

fbird_gen_id(string $generator, int $increment = 1, resource $link_identifier = null): int|string|false

Beschreibung

fbird_gen_id() erhöht den angegebenen Generator (auch bekannt als Sequenz) in einer Firebird- oder InterBase-Datenbank um den Wert increment und liefert den resultierenden neuen Wert zurück. Generatoren sind datenbankweite, transaktionsunabhängige Zähler, die typischerweise zur Erzeugung eindeutiger Primärschlüssel verwendet werden.

Im Gegensatz zu Sequenzwerten innerhalb von Transaktionen sind Generatorwerte in Firebird/InterBase global und sofort sichtbar – sie werden nicht zurückgerollt, selbst wenn die zugehörige Transaktion abgebrochen wird. Dies macht sie ideal für die Erzeugung eindeutiger IDs, sollte aber bei der Planung berücksichtigt werden.

Der Parameter increment kann auch negativ sein oder 0 betragen: Mit 0 lässt sich der aktuelle Wert des Generators auslesen, ohne ihn zu verändern. Wird keine Datenbankverbindung (link_identifier) angegeben, wird die zuletzt geöffnete Verbindung verwendet.

Hinweis: Diese Funktion ist ein Alias für ibase_gen_id() und steht nur zur Verfügung, wenn die ibase-Erweiterung kompiliert und geladen ist.

Parameter

Name	Typ	Default	Beschreibung
$generator Pflicht	string		Name des Generators (Sequenz) in der Datenbank, dessen Wert erhöht werden soll.
$increment	int	1	Wert, um den der Generator erhöht wird. Negative Werte verringern den Generator; der Wert `0` liest den aktuellen Stand aus, ohne ihn zu ändern.
$link_identifier	resource		Eine Firebird/InterBase-Datenbankverbindung, die mit `ibase_connect()` oder `ibase_pconnect()` geöffnet wurde. Wird dieser Parameter weggelassen, wird die zuletzt geöffnete Verbindung verwendet.

Rückgabewert

Typ

int|string|false

Beschreibung

Gibt den neuen Wert des Generators als int oder – bei sehr großen Werten, die den PHP-Integer-Bereich überschreiten – als string zurück. Im Fehlerfall wird false zurückgegeben.

Beispiele

Eindeutige ID für einen neuen Datensatz erzeugen

<?php
$dbh = ibase_connect('localhost:pfad/zur/datenbank.fdb', 'sysdba', 'masterkey');

// Generator 'GEN_KUNDEN_ID' um 1 erhöhen und neuen Wert abrufen
$neueId = fbird_gen_id('GEN_KUNDEN_ID', 1, $dbh);

if ($neueId === false) {
    echo 'Fehler beim Abrufen der Generator-ID.';
} else {
    echo 'Neue Kunden-ID: ' . $neueId;

    // Datensatz mit der erzeugten ID einfügen
    ibase_query($dbh, "INSERT INTO KUNDEN (ID, NAME) VALUES ($neueId, 'Max Mustermann')");
}

ibase_close($dbh);

Neue Kunden-ID: 42

Aktuellen Generatorwert auslesen ohne Erhöhung

<?php
$dbh = ibase_connect('localhost:pfad/zur/datenbank.fdb', 'sysdba', 'masterkey');

// Mit increment = 0 wird der Generator nicht verändert
$aktuellerWert = fbird_gen_id('GEN_KUNDEN_ID', 0, $dbh);

echo 'Aktueller Wert des Generators GEN_KUNDEN_ID: ' . $aktuellerWert;

ibase_close($dbh);

Aktueller Wert des Generators GEN_KUNDEN_ID: 42

// Wichtig · Fallstricke

Transaktionssicherheit: Generatorwerte sind in Firebird/InterBase explizit transaktionsunabhängig. Ein Rollback der Transaktion setzt den Generatorwert nicht zurück. Daher können bei abgebrochenen Transaktionen Lücken in den erzeugten ID-Sequenzen entstehen – dies ist normales und erwartetes Verhalten.

Alias: fbird_gen_id() ist ein Alias von ibase_gen_id(). Beide Funktionen verhalten sich identisch. Es wird empfohlen, in neuem Code einheitlich eine der beiden Varianten zu verwenden.

Verfügbarkeit: Die Funktion setzt voraus, dass die PHP-Erweiterung ibase (Firebird/InterBase) installiert und aktiviert ist. Ab PHP 7.4 wurde die ibase-Erweiterung aus dem PHP-Kern ausgelagert und muss über PECL oder eine externe Distribution bereitgestellt werden.

Siehe auch

ibase_gen_id ibase_connect ibase_query fbird_query fbird_connect