Signatur
Beschreibung
fbird_set_event_handler() ermöglicht es, eine PHP-Funktion als Ereignis-Handler für einen oder mehrere benannte Datenbankereignisse in einer Firebird- oder InterBase-Datenbank zu registrieren. Sobald ein registriertes Ereignis in der Datenbank ausgelöst wird (z. B. durch einen Trigger oder eine gespeicherte Prozedur via POST_EVENT), ruft die Extension automatisch den angegebenen Callback auf.
Der Callback erhält als Parameter den Namen des aufgetretenen Ereignisses sowie die Anzahl der seit der letzten Benachrichtigung ausgelösten Ereignisse. Dies erlaubt reaktive Programmierung auf Datenbankebene, ohne die Datenbank in kurzen Intervallen pollen zu müssen.
Die Funktion gibt eine Ressource zurück, die den registrierten Event-Handler repräsentiert. Diese Ressource wird benötigt, um den Handler später mit fbird_free_event_handler() wieder zu deregistrieren. Mehrere Ereignisnamen können gleichzeitig überwacht werden, indem sie als weitere Argumente übergeben werden.
Hinweis: fbird_set_event_handler() ist ein Alias für ibase_set_event_handler(). Die InterBase/Firebird-Extension (ibase) wurde in PHP 8.0 aus dem PHP-Core entfernt und ist seitdem nur noch als PECL-Paket (php-firebird) verfügbar.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $callback Pflicht | callable | Die PHP-Callback-Funktion, die bei jedem Auftreten eines registrierten Ereignisses aufgerufen wird. Die Funktion erhält als erstes Argument den string Namen des Ereignisses und als zweites Argument die int Anzahl der Ereignis-Auslösungen seit der letzten Benachrichtigung. |
|
| $event_name Pflicht | string | Der Name des ersten zu überwachenden Datenbankereignisses. Dieser Name muss mit dem Namen übereinstimmen, der in der Datenbank via POST_EVENT verwendet wird. |
|
| $event_names | string | Optionale weitere Ereignisnamen, die ebenfalls überwacht werden sollen. Jeder zusätzliche Name wird als eigenes Argument übergeben. |
Rückgabewert
fbird_free_event_handler() übergeben werden, um die Ereignisüberwachung wieder zu beenden. Im Fehlerfall wird false zurückgegeben.Beispiele
Einfacher Ereignis-Handler für ein Firebird-Ereignis
<?php
// Verbindung zur Firebird-Datenbank herstellen
$dbh = fbird_connect('localhost:/path/to/database.fdb', 'SYSDBA', 'masterkey');
// Callback-Funktion definieren
function meinEreignisHandler(string $ereignisName, int $anzahl): void
{
echo "Ereignis '{$ereignisName}' wurde {$anzahl} Mal ausgelöst." . PHP_EOL;
}
// Event-Handler registrieren
$handler = fbird_set_event_handler('meinEreignisHandler', 'NEUER_AUFTRAG', 'AUFTRAG_GEAENDERT');
if ($handler === false) {
die('Fehler beim Registrieren des Event-Handlers.');
}
echo 'Event-Handler registriert. Warte auf Ereignisse...' . PHP_EOL;
// Auf Ereignisse warten (blockiert bis ein Ereignis eintrifft)
fbird_wait_event($dbh, 'NEUER_AUFTRAG', 'AUFTRAG_GEAENDERT');
// Handler wieder freigeben
fbird_free_event_handler($handler);
fbird_close($dbh);
?>
Ereignis-Handler mit anonymer Funktion und Datenbankverbindung
<?php
$dbh = fbird_connect('localhost:/data/meine_db.fdb', 'SYSDBA', 'masterkey');
// Anonyme Callback-Funktion mit Closure
$handler = fbird_set_event_handler(
function (string $ereignis, int $anzahl) use ($dbh): void {
echo date('H:i:s') . " | Ereignis: {$ereignis} | Anzahl: {$anzahl}" . PHP_EOL;
// Auf neue Datensätze reagieren
if ($ereignis === 'LAGER_AKTUALISIERT') {
$result = fbird_query($dbh, 'SELECT * FROM lager WHERE status = 0');
while ($row = fbird_fetch_assoc($result)) {
echo ' -> Artikel: ' . $row['ARTIKEL_NR'] . ' | Menge: ' . $row['MENGE'] . PHP_EOL;
}
}
},
'LAGER_AKTUALISIERT',
'LAGER_FEHLER'
);
if ($handler) {
// Auf Ereignisse warten
fbird_wait_event($dbh, 'LAGER_AKTUALISIERT', 'LAGER_FEHLER');
fbird_free_event_handler($handler);
}
fbird_close($dbh);
?>
// Wichtig · Fallstricke
PHP-Version: Die InterBase/Firebird-Extension wurde mit PHP 8.0 aus dem PHP-Core entfernt. Für PHP 8.x muss das PECL-Paket php-firebird installiert werden. fbird_set_event_handler() ist ein Alias für ibase_set_event_handler().
Blockierendes Verhalten: Die Ereignisüberwachung in Verbindung mit fbird_wait_event() ist blockierend. Für Web-Applikationen ist dies meist ungeeignet; das Muster eignet sich eher für CLI-Skripte oder Hintergrundprozesse.
Ressourcen-Verwaltung: Der von fbird_set_event_handler() zurückgegebene Handler muss nach Gebrauch mit fbird_free_event_handler() freigegeben werden, um Ressourcenlecks zu vermeiden.
Firebird-Seitig: Die Ereignisse müssen in der Datenbank korrekt via POST_EVENT 'EREIGNIS_NAME'; in Triggern oder Stored Procedures definiert sein, damit sie ausgelöst werden können.