Signatur
Beschreibung
ibase_set_event_handler() ermöglicht es, auf serverseitige Ereignisse einer Firebird- oder InterBase-Datenbank zu reagieren, ohne aktiv pollen zu müssen. Die übergebene Rückruffunktion wird von der PHP-Laufzeit aufgerufen, sobald die Datenbank eines der genannten Ereignisse auslöst – typischerweise über POST_EVENT in gespeicherten Prozeduren oder Triggern.
Die Funktion gibt eine Event-Ressource zurück, mit der das Ereignis-Handling später über ibase_free_event_handler() wieder aufgehoben werden kann. Alternativ kann ein Datenbankverbindungs-Handle als erstes Argument übergeben werden, um die Events einer bestimmten Verbindung zu überwachen.
Die Rückruffunktion erhält als Parameter den Ereignisnamen sowie die Anzahl, wie oft das Ereignis seit dem letzten Aufruf aufgetreten ist. Gibt die Callback-Funktion false zurück, wird der Event-Handler automatisch deregistriert.
Diese Funktion ist besonders nützlich in lang laufenden PHP-Skripten oder Daemons, die auf Datenbank-seitige Änderungen reagieren sollen, ohne kontinuierlich Abfragen auszuführen und damit die Datenbankverbindung zu belasten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $callback Pflicht | callable | Die Rückruffunktion, die bei Auftreten eines Ereignisses aufgerufen wird. Sie erhält den Ereignisnamen (string) und die Anzahl der Auftritte (int) als Parameter. Gibt sie false zurück, wird der Handler deregistriert. |
|
| $event_name Pflicht | string | Der Name des ersten Datenbankereignisses, auf das gewartet werden soll. Entspricht dem Namen, der in der Datenbank via POST_EVENT ausgelöst wird. |
|
| $event_names | string | Optionale weitere Ereignisnamen. Es können bis zu 15 Ereignisse gleichzeitig überwacht werden. |
Rückgabewert
ibase_free_event_handler() wieder freigegeben werden kann. Im Fehlerfall wird false zurückgegeben.Beispiele
Einfacher Event-Handler für ein Datenbankereignis
<?php
$dbh = ibase_connect('localhost:employee', 'sysdba', 'masterkey');
function meinEventHandler(string $ereignisName, int $anzahl): void
{
echo "Ereignis '{$ereignisName}' trat {$anzahl} Mal auf.\n";
}
$handler = ibase_set_event_handler('meinEventHandler', 'NEUER_AUFTRAG', 'AUFTRAG_GELOESCHT');
// Warte auf Ereignisse (in einem echten Daemon würde hier eine Schleife laufen)
ibase_wait_event($dbh, 'NEUER_AUFTRAG');
ibase_free_event_handler($handler);
ibase_close($dbh);Handler automatisch deregistrieren nach erstem Ereignis
<?php
$dbh = ibase_connect('localhost:employee', 'sysdba', 'masterkey');
$handler = ibase_set_event_handler(
function (string $ereignisName, int $anzahl): bool {
echo "Einmaliges Ereignis '{$ereignisName}' empfangen (Anzahl: {$anzahl}).\n";
// Rückgabe von false deregistriert den Handler automatisch
return false;
},
'EINMALIGES_EVENT'
);
// Warte, bis das Ereignis eintrifft
ibase_wait_event($dbh, 'EINMALIGES_EVENT');
ibase_close($dbh);// Wichtig · Fallstricke
Deprecation-Hinweis: Die ibase_*-Funktionen wurden mit PHP 8.0.0 aus dem PHP-Kern entfernt und in die PECL-Erweiterung ibase bzw. Firebird ausgelagert. Für aktuelle Projekte sollte die PECL-Erweiterung oder eine alternative Datenbank-Abstraktion verwendet werden.
Es können maximal 15 Ereignisnamen pro Handler-Aufruf registriert werden. Bei mehr Ereignissen müssen mehrere Handler angelegt werden.
Die Funktion blockiert nicht von sich aus – sie registriert lediglich den Handler. Um tatsächlich auf Ereignisse zu warten, muss ibase_wait_event() verwendet oder die Skriptausführung anderweitig am Laufen gehalten werden.
In einer Webserver-Umgebung ist der Einsatz dieser Funktion wenig sinnvoll, da HTTP-Anfragen zeitlich begrenzt sind. Sie eignet sich vorwiegend für CLI-Skripte oder Daemon-Prozesse.