restore_exception_handler — Funktion · PHP-Referenz

Signatur

restore_exception_handler(): true

Beschreibung

restore_exception_handler() setzt den aktiven Exception-Handler auf den Handler zurück, der vor dem letzten Aufruf von set_exception_handler() aktiv war. Damit kann ein vorübergehend gesetzter Handler wieder entfernt und der ursprüngliche Zustand wiederhergestellt werden.

Die Funktion arbeitet mit einem internen Stack: Jeder Aufruf von set_exception_handler() legt den aktuellen Handler auf diesen Stack, und restore_exception_handler() holt den obersten Eintrag wieder herunter. Wenn kein benutzerdefinierter Handler mehr auf dem Stack liegt, wird der interne PHP-Standard-Handler aktiv.

Typischer Einsatz ist das vorübergehende Überschreiben des Exception-Handlers innerhalb einer Bibliothek oder eines Frameworks, wobei am Ende der eigene Handler wieder entfernt wird, um den Handler des aufrufenden Codes nicht dauerhaft zu verändern. Dies entspricht dem Prinzip der minimalen Nebeneffekte.

Ab PHP 8.0 gibt die Funktion immer true zurück. In früheren Versionen war der Rückgabewert ebenfalls stets true, aber formal als bool definiert.

Rückgabewert

Typ

true

Beschreibung

Gibt immer true zurück.

Beispiele

Temporärer Exception-Handler mit anschließender Wiederherstellung

<?php
function meinHandler(Throwable $e): void {
    echo 'Mein Handler: ' . $e->getMessage() . PHP_EOL;
}

// Standard-Handler merken und eigenen setzen
set_exception_handler('meinHandler');

// ... Code, der den eigenen Handler nutzt ...
throw new RuntimeException('Testfehler');

// Eigenen Handler wieder entfernen – Standard wird reaktiviert
restore_exception_handler();

Mein Handler: Testfehler

Verschachteltes Setzen und Wiederherstellen von Handlern

<?php
function handlerA(Throwable $e): void {
    echo 'Handler A: ' . $e->getMessage() . PHP_EOL;
}

function handlerB(Throwable $e): void {
    echo 'Handler B: ' . $e->getMessage() . PHP_EOL;
}

set_exception_handler('handlerA'); // Stack: [A]
set_exception_handler('handlerB'); // Stack: [A, B] — B ist aktiv

// Aktiven Handler (B) entfernen → A wird wieder aktiv
restore_exception_handler(); // Stack: [A]

// A wieder entfernen → PHP-Standard wird aktiv
restore_exception_handler(); // Stack: []

echo 'Handler erfolgreich wiederhergestellt.' . PHP_EOL;

Handler erfolgreich wiederhergestellt.

// Wichtig · Fallstricke

Reihenfolge beachten: Jeder Aufruf von restore_exception_handler() entfernt nur einen Handler vom Stack. Wurden mehrere Handler gesetzt, sind entsprechend viele Wiederherstellungsaufrufe nötig.

Kein Fehler bei leerem Stack: Wird restore_exception_handler() aufgerufen, obwohl kein benutzerdefinierter Handler auf dem Stack liegt, passiert nichts Schädliches — PHP verbleibt beim internen Standard-Handler.

Die Funktion ist das Gegenstück zu restore_error_handler(), welches für klassische PHP-Fehler (nicht Exceptions) zuständig ist.

Siehe auch

set_exception_handler restore_error_handler set_error_handler get_exception