oci_register_taf_callback — Funktion · PHP-Referenz

Signatur

oci_register_taf_callback(resource $connection, callable|null $callback): bool

Beschreibung

oci_register_taf_callback() ermöglicht es, eine PHP-Callback-Funktion zu registrieren, die automatisch aufgerufen wird, wenn Oracle Database TAF (Transparent Application Failover) einen Failover-Ereignis auslöst. TAF ist ein Oracle-Feature, das bei einem Verbindungsabbruch zur Datenbank automatisch eine neue Verbindung zu einem Standby-System aufbaut, ohne dass die Anwendung dies explizit handhaben muss.

Die registrierte Callback-Funktion empfängt dabei Informationen über den aktuellen Failover-Status (z. B. OCI_FO_BEGIN, OCI_FO_END, OCI_FO_ABORT, OCI_FO_ERROR oder OCI_FO_REAUTH) und den Typ des Failovers (OCI_FO_SESSION oder OCI_FO_SELECT). Anhand dieser Informationen kann die Anwendung entsprechend reagieren, etwa Sitzungszustand wiederherstellen oder den Benutzer informieren.

Diese Funktion ist besonders nützlich in Hochverfügbarkeitsszenarien mit Oracle Real Application Clusters (RAC) oder Oracle Data Guard, wo Failover-Ereignisse transparent und automatisch behandelt werden sollen. Der Callback kann den Failover-Prozess auch steuern: Gibt er OCI_FO_RETRY zurück, wird der Failover erneut versucht.

Um einen bereits registrierten Callback zu entfernen, kann null als $callback-Parameter übergeben werden.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	resource		Eine gültige OCI8-Datenbankverbindung, die mit `oci_connect()`, `oci_pconnect()` oder `oci_new_connect()` erstellt wurde.
$callback Pflicht	callable\|null		Die Callback-Funktion, die bei einem TAF-Ereignis aufgerufen wird. Sie muss die Signatur `callback(resource $connection, int $event, int $type): int` haben. Wird `null` übergeben, wird ein bereits registrierter Callback entfernt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Verbindung oder ungültiger Callback).

Beispiele

Einfache TAF-Callback-Registrierung

<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');

if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

function meinTafCallback($connection, $event, $type): int
{
    switch ($event) {
        case OCI_FO_BEGIN:
            echo "Failover gestartet (Typ: $type)\n";
            break;
        case OCI_FO_END:
            echo "Failover erfolgreich abgeschlossen.\n";
            break;
        case OCI_FO_ABORT:
            echo "Failover abgebrochen!\n";
            break;
        case OCI_FO_ERROR:
            echo "Failover-Fehler aufgetreten. Wiederhole...\n";
            return OCI_FO_RETRY;
        case OCI_FO_REAUTH:
            echo "Benutzer wird erneut authentifiziert.\n";
            break;
    }
    return 0;
}

$result = oci_register_taf_callback($conn, 'meinTafCallback');

if ($result) {
    echo "TAF-Callback erfolgreich registriert.\n";
} else {
    echo "Fehler beim Registrieren des TAF-Callbacks.\n";
}

// Datenbankoperationen ...

oci_close($conn);
?>

TAF-Callback erfolgreich registriert.

TAF-Callback mit Closure und anschließendem Entfernen

<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');

if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

$tafCallback = function ($connection, $event, $type): int {
    $ereignisse = [
        OCI_FO_BEGIN  => 'BEGIN',
        OCI_FO_END    => 'END',
        OCI_FO_ABORT  => 'ABORT',
        OCI_FO_ERROR  => 'ERROR',
        OCI_FO_REAUTH => 'REAUTH',
    ];
    $typen = [
        OCI_FO_SESSION => 'SESSION',
        OCI_FO_SELECT  => 'SELECT',
    ];

    $ereignisName = $ereignisse[$event] ?? 'UNBEKANNT';
    $typName      = $typen[$type]   ?? 'UNBEKANNT';

    echo "TAF-Ereignis: $ereignisName, Typ: $typName\n";

    if ($event === OCI_FO_ERROR) {
        return OCI_FO_RETRY; // Failover erneut versuchen
    }
    return 0;
};

// Callback registrieren
oci_register_taf_callback($conn, $tafCallback);

// ... Datenbankoperationen ...

// Callback wieder entfernen
oci_register_taf_callback($conn, null);
echo "TAF-Callback entfernt.\n";

oci_close($conn);
?>

TAF-Callback entfernt.

// Wichtig · Fallstricke

Voraussetzungen: TAF-Callbacks funktionieren nur, wenn die Oracle-Datenbank und der Client entsprechend für TAF konfiguriert sind (z. B. Oracle RAC oder Data Guard mit entsprechenden TNS-Einstellungen). Ohne diese Konfiguration wird der Callback niemals aufgerufen.

Rückgabewert des Callbacks: Gibt der Callback bei einem OCI_FO_ERROR-Ereignis den Wert OCI_FO_RETRY zurück, versucht Oracle, den Failover zu wiederholen. Alle anderen Rückgabewerte werden ignoriert.

Persistente Verbindungen: Bei persistenten Verbindungen (oci_pconnect()) bleibt der Callback über mehrere Anfragen hinweg erhalten. Dies kann zu unerwartetem Verhalten führen, wenn sich die Callback-Logik zwischen Anfragen unterscheiden soll.

Thread-Sicherheit: In einer Multi-Thread-Umgebung (z. B. PHP-FPM oder Apache mit Threads) ist besondere Vorsicht geboten, da der Callback aus einem Oracle-internen Thread heraus aufgerufen werden kann.

Siehe auch

oci_connect oci_pconnect oci_new_connect oci_error