set_exception_handler — Funktion · PHP-Referenz

Signatur

set_exception_handler(callable|null $callback): callable|null

Beschreibung

set_exception_handler() erlaubt es, eine eigene Funktion zu registrieren, die aufgerufen wird, wenn eine Exception nicht durch einen try/catch-Block abgefangen wird. Dies ist nützlich, um in Produktivumgebungen einen zentralen Fehlerbehandlungspunkt zu schaffen, z. B. um Fehler zu loggen, eine benutzerfreundliche Fehlerseite auszugeben oder Ressourcen freizugeben, bevor das Skript beendet wird.

Der übergebene Callback erhält als einziges Argument das Throwable-Objekt (ab PHP 7.0; zuvor Exception), das die nicht abgefangene Exception beschreibt. Nach dem Aufruf des Handlers wird das Skript regulär beendet – der Handler ersetzt nicht die normale Skriptausführung, sondern wird nur im Fehlerfall aktiv.

Wird null übergeben, wird der aktuelle Handler zurückgesetzt und der zuletzt gesetzte Handler zurückgegeben. So lässt sich ein Handler temporär ersetzen und anschließend wiederherstellen. Mehrere aufeinanderfolgende Aufrufe überschreiben sich gegenseitig; es gibt keine Handler-Kette wie bei set_error_handler().

Typische Einsatzszenarien sind zentrales Logging mit Bibliotheken wie Monolog, die Ausgabe strukturierter JSON-Fehlerantworten in APIs oder die Anzeige einer generischen Fehlerseite für Endnutzer, ohne sensible Stack-Trace-Informationen preiszugeben.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	callable\|null		Eine aufrufbare Funktion (oder `null` zum Zurücksetzen), die ein `Throwable`-Objekt als einzigen Parameter empfängt. Die Signatur sollte lauten: `function(Throwable $exception): void`.

Rückgabewert

Typ

callable|null

Beschreibung

Gibt den zuvor registrierten Exception-Handler zurück (als callable), oder null, wenn kein Handler zuvor gesetzt war.

Beispiele

Einfacher globaler Exception-Handler mit Logging

<?php
function meinExceptionHandler(Throwable $e): void {
    // Fehler in Datei loggen
    error_log(sprintf(
        "[EXCEPTION] %s: %s in %s:%d",
        get_class($e),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    ));

    // Benutzerfreundliche Ausgabe
    http_response_code(500);
    echo "<h1>Ein unerwarteter Fehler ist aufgetreten.</h1>";
    echo "<p>Bitte versuchen Sie es später erneut.</p>";
}

set_exception_handler('meinExceptionHandler');

// Diese Exception wird nicht abgefangen und löst den Handler aus
throw new RuntimeException('Datenbankverbindung fehlgeschlagen');

<h1>Ein unerwarteter Fehler ist aufgetreten.</h1> <p>Bitte versuchen Sie es später erneut.</p>

Handler temporär ersetzen und wiederherstellen

<?php
function standardHandler(Throwable $e): void {
    echo "Standard-Handler: " . $e->getMessage() . PHP_EOL;
}

function spezialHandler(Throwable $e): void {
    echo "Spezial-Handler: " . $e->getMessage() . PHP_EOL;
}

// Standard-Handler setzen
set_exception_handler('standardHandler');

// Spezial-Handler setzen und alten Handler merken
$alter = set_exception_handler('spezialHandler');
echo get_class($alter) === 'Closure' ? 'Closure' : (is_string($alter) ? $alter : 'unbekannt');
// Alten Handler wiederherstellen
set_exception_handler($alter);

echo "Handler wiederhergestellt." . PHP_EOL;

// Löst standardHandler aus
throw new LogicException('Testfehler');

standardHandler Handler wiederhergestellt. Standard-Handler: Testfehler

JSON-Fehlerantwort in einer REST-API

<?php
set_exception_handler(function (Throwable $e): void {
    http_response_code(500);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode([
        'error'   => true,
        'message' => 'Interner Serverfehler',
        'code'    => $e->getCode(),
        // Stack-Trace NUR in Entwicklungsumgebungen ausgeben!
        'details' => (getenv('APP_ENV') === 'development') ? $e->getTraceAsString() : null,
    ]);
});

throw new \InvalidArgumentException('Ungültige Eingabe', 400);

{"error":true,"message":"Interner Serverfehler","code":400,"details":null}

// Wichtig · Fallstricke

Sicherheit: Geben Sie Stack-Traces und interne Fehlermeldungen niemals in Produktivumgebungen an Endnutzer aus – sie können sensible Pfade, Datenbankstruktur oder Konfigurationsdaten enthalten. Loggen Sie Details serverseitig und zeigen Sie dem Nutzer nur generische Meldungen.

PHP 7+: Der Callback-Parameter sollte als Throwable typisiert sein, da ab PHP 7 sowohl Exception als auch Error (z. B. TypeError, ParseError) über diesen Handler abgefangen werden. In PHP 5 war nur Exception möglich.

Kein Ersatz für try/catch: Der Handler wird erst aufgerufen, nachdem alle try/catch-Blöcke versagt haben. Er ist als letztes Sicherheitsnetz gedacht, nicht als primäre Fehlerbehandlungsstrategie.

Skriptende: Nach dem Aufruf des Handlers wird das PHP-Skript normal beendet. Es ist nicht möglich, die Skriptausführung im Handler fortzusetzen.

Siehe auch

set_error_handler restore_exception_handler get_exception_handler error_reporting Throwable Exception Error