fbird_wait_event — Funktion · PHP-Referenz

Signatur

fbird_wait_event(resource $link_identifier, string $event_name, string ...$event_names): string|false

Beschreibung

fbird_wait_event() (auch als ibase_wait_event() bekannt) ist eine blockierende Funktion für die Firebird- und InterBase-Datenbankschnittstelle in PHP. Sie wartet darauf, dass die Datenbank ein benanntes Ereignis auslöst, und gibt erst dann die Kontrolle an das PHP-Skript zurück.

Ereignisse in Firebird/InterBase werden serverseitig typischerweise durch Stored Procedures oder Trigger mittels der POST_EVENT-Anweisung erzeugt. Mit fbird_wait_event() kann ein PHP-Skript reagieren, sobald ein solches Ereignis eintritt – beispielsweise wenn neue Datensätze eingefügt werden oder ein bestimmter Geschäftsprozess abgeschlossen ist. Dies ermöglicht eine ereignisgesteuerte Datenbankprogrammierung ohne aktives Polling.

Es können mehrere Ereignisnamen übergeben werden. Die Funktion kehrt zurück, sobald eines der genannten Ereignisse ausgelöst wurde, und gibt dessen Namen als String zurück. Tritt kein Ereignis ein, blockiert die Funktion unbegrenzt (oder bis zum PHP-Ausführungs-Timeout).

Alternativ kann auch die nicht-blockierende Variante fbird_set_event_handler() verwendet werden, die beim Eintreten eines Ereignisses einen Callback aufruft, ohne den Skriptablauf zu unterbrechen.

Parameter

Name	Typ	Beschreibung
$link_identifier	resource	Eine gültige Firebird/InterBase-Datenbankverbindungs-Ressource, die zuvor mit `fbird_connect()` oder `fbird_pconnect()` erstellt wurde. Wird dieser Parameter weggelassen, wird die zuletzt geöffnete Verbindung verwendet.
$event_name Pflicht	string	Der Name des ersten Firebird/InterBase-Ereignisses, auf das gewartet werden soll. Der Name muss exakt dem Namen entsprechen, der serverseitig mit `POST_EVENT` ausgelöst wird.
$event_names	string	Optionale weitere Ereignisnamen (variadic). Die Funktion kehrt zurück, sobald eines der angegebenen Ereignisse eintritt.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den Namen des Ereignisses zurück, das als erstes ausgelöst wurde. Im Fehlerfall wird false zurückgegeben.

Beispiele

Warten auf ein einzelnes Datenbankereignis

<?php
// Verbindung zur Firebird-Datenbank herstellen
$dbh = fbird_connect('localhost:/var/db/meine_datenbank.fdb', 'SYSDBA', 'masterkey');

if (!$dbh) {
    die('Verbindung fehlgeschlagen: ' . fbird_errmsg());
}

echo "Warte auf Ereignis 'NEUER_AUFTRAG'...\n";

// Blockiert, bis der Trigger/die SP 'POST_EVENT NEUER_AUFTRAG' aufruft
$ereignis = fbird_wait_event($dbh, 'NEUER_AUFTRAG');

if ($ereignis !== false) {
    echo "Ereignis eingetreten: " . $ereignis . "\n";
} else {
    echo "Fehler beim Warten auf Ereignis: " . fbird_errmsg() . "\n";
}

fbird_close($dbh);

Warte auf Ereignis 'NEUER_AUFTRAG'... Ereignis eingetreten: NEUER_AUFTRAG

Warten auf mehrere Ereignisse gleichzeitig

<?php
$dbh = fbird_connect('localhost:/var/db/lager.fdb', 'SYSDBA', 'masterkey');

if (!$dbh) {
    die('Verbindung fehlgeschlagen.');
}

echo "Warte auf Lager-Ereignisse...\n";

// Kehrt zurück, sobald EINES der drei Ereignisse eintritt
$ereignis = fbird_wait_event(
    $dbh,
    'WARENEINGANG',
    'WARENAUSGANG',
    'INVENTUR_ABGESCHLOSSEN'
);

switch ($ereignis) {
    case 'WARENEINGANG':
        echo "Neuer Wareneingang wurde registriert.\n";
        break;
    case 'WARENAUSGANG':
        echo "Warenausgang wurde verbucht.\n";
        break;
    case 'INVENTUR_ABGESCHLOSSEN':
        echo "Inventur wurde abgeschlossen.\n";
        break;
    default:
        echo "Unbekanntes oder kein Ereignis: " . var_export($ereignis, true) . "\n";
}

fbird_close($dbh);

Warte auf Lager-Ereignisse... Neuer Wareneingang wurde registriert.

// Wichtig · Fallstricke

Blocking-Verhalten: fbird_wait_event() blockiert die gesamte PHP-Skriptausführung, bis ein Ereignis eintritt. Das PHP-Skript reagiert daher nicht auf andere Anfragen, solange es wartet. Bei Webserver-Einsatz kann dies zu Verbindungs-Timeouts führen. Die Funktion eignet sich daher eher für CLI-Skripte oder Hintergrundprozesse.

Ausführungs-Timeout: Das per max_execution_time konfigurierte PHP-Limit gilt auch hier. Für langlebige Warteprozesse sollte das Timeout mit set_time_limit(0) deaktiviert werden.

Alias: fbird_wait_event() ist ein Alias für ibase_wait_event(). Beide Funktionen sind Teil der ibase-Extension (Firebird/InterBase). Die Extension wurde in PHP 7.4 aus dem PHP-Kern ausgelagert und steht seitdem als eigenständige PECL-Extension ibase zur Verfügung. In PHP 8.x muss sie gesondert installiert werden.

Alternative: Für nicht-blockierende Ereignisverarbeitung steht fbird_set_event_handler() zur Verfügung, das einen Callback registriert und die Skriptausführung nicht anhält.

Siehe auch

fbird_set_event_handler fbird_free_event_handler fbird_connect ibase_wait_event