restore_exception_handler()

Einführung

PHP ermöglicht es, einen globalen Exception-Handler mit set_exception_handler() zu installieren — einen Callback, der ausgeführt wird, wenn eine Ausnahme unbehandelt bis ganz nach oben gelangt. restore_exception_handler() ist das Gegenstück: Es entfernt den aktuell oben auf dem Stack befindlichen Handler und reaktiviert den zuvor aktiven. Diese Seite erläutert, was die Funktion tut, ihren genauen Rückgabewert und wann ihr Einsatz sinnvoll ist.

Wie der Exception-Handler-Stack funktioniert

Jeder Aufruf von set_exception_handler() schiebt einen Handler auf einen internen Stack. Nur die oberste Ebene des Stacks ist jeweils aktiv. restore_exception_handler() entfernt den obersten Eintrag, sodass der zuvor installierte Handler (oder PHP's eingebauter Standard, wenn der Stack leer wird) wieder übernimmt.

Dieses Push/Pop-Modell macht die Funktion nützlich: Eine Bibliothek oder ein Codeblock kann vorübergehend einen eigenen Handler installieren und anschließend den Handler des Aufrufers wiederherstellen — ohne wissen zu müssen, welcher Handler das war.

Wenn Sie neu im Umgang mit Ausnahmen sind, beginnen Sie mit PHP Exceptions und dem try/catch-Kapitel; restore_exception_handler() betrifft ausschließlich den globalen Handler für unbehandelte Ausnahmen, nicht die catch-Blöcke, die Sie inline schreiben.

Syntax

restore_exception_handler(): true

Die Funktion erwartet keine Parameter und gibt immer true zurück. Sie gibt nicht den entfernten Handler zurück — um den vorherigen Handler zu lesen, speichern Sie den Rückgabewert von set_exception_handler() (der den Handler zurückgibt, der aktiv war, bevor er gesetzt wurde).

Beispiel: den Handler vorübergehend überschreiben

Das folgende Snippet installiert einen Basis-Handler, überschreibt ihn dann vorübergehend für einen Codeabschnitt und stellt den Basis-Handler danach wieder her:

<?php
function base_handler($e) {
    echo "Base: " . $e->getMessage() . "\n";
}

function temp_handler($e) {
    echo "Temp: " . $e->getMessage() . "\n";
}

set_exception_handler('base_handler');
set_exception_handler('temp_handler'); // pushes temp on top

restore_exception_handler();           // pops temp, base is active again

// Because this exception is never caught, the active global handler runs:
throw new Exception("something failed");

Ausgabe:

Base: something failed

Der temp_handler wurde durch restore_exception_handler() entfernt, sodass beim Auftreten der unbehandelten Ausnahme am Ende des Skripts stattdessen base_handler ausgeführt wird. Beachten Sie, dass der globale Handler nur für unbehandelte Ausnahmen ausgelöst wird — alles, was in einem passenden try/catch eingeschlossen ist, erreicht ihn nicht.

Den vorherigen Handler auslesen

restore_exception_handler() selbst gibt den entfernten Handler nicht zurück. Wenn Sie wissen müssen, welcher Callable aktiv war, bevor Sie ihn überschrieben haben, speichern Sie den Rückgabewert von set_exception_handler():

<?php
set_exception_handler('base_handler');

// set_exception_handler() returns the handler it replaced:
$previous = set_exception_handler('temp_handler');

var_dump($previous); // string(12) "base_handler"

restore_exception_handler(); // back to base_handler

Wann verwenden

• Begrenzte Überschreibungen. Eine Routine installiert ihren eigenen Handler für die Dauer einer Aufgabe und ruft danach restore_exception_handler() auf, damit der Rest des Programms das ursprüngliche Verhalten beibehält.
• Bibliotheken. Code, der nicht Eigentümer des globalen Handlers ist, kann ihn vorübergehend borgen und anschließend zurückgeben.
• Aufräum- und Shutdown-Logik. Einen temporären Handler rückgängig machen, bevor das Skript beendet wird, damit er nicht in späteren Code übergeht.

Dies betrifft ausschließlich Exception-Handler — um einen mit set_error_handler() gesetzten Standard-Fehlerhandler wiederherzustellen, verwenden Sie stattdessen restore_error_handler().

Diagramm

graph TD
A[set_exception_handler base] --> B[set_exception_handler temp pushes on top]
B --> C[restore_exception_handler pops temp]
C --> D[base handler active again]
D --> E[Uncaught exception runs base handler]

Übungsaufgaben