set_exception_handler()

Einführung

set_exception_handler() registriert eine Funktion, die PHP immer dann aufruft, wenn eine unbehandelte Ausnahme den Anfang des Skripts erreicht. Normalerweise erzeugt eine unbehandelte Ausnahme einen schwerwiegenden Fehler und einen Standard-Stack-Trace; ein globaler Handler ermöglicht es, dies durch konsistentes Logging, eine benutzerfreundliche Fehlerseite oder Benachrichtigungen zu ersetzen — an einer einzigen Stelle für die gesamte Anwendung. Diese Seite behandelt die Signatur der Funktion, was sie zurückgibt, ein ausführbares Beispiel, die Fälle, die sie nicht abdeckt, und wichtige Stolperfallen.

Wenn Sie zunächst die Grundlagen des Werfens und Abfangens von Ausnahmen benötigen, beginnen Sie mit PHP Exceptions und dem try/catch-Kapitel.

Wann wird der Handler aufgerufen?

Eine normale Ausnahme wird vom nächsten passenden catch-Block abgefangen. Der globale Handler wird nur ausgeführt, wenn kein catch-Block übereinstimmt — die Ausnahme „entkommt" vollständig aus dem Skript:

try {
    throw new RuntimeException('handled here');
} catch (RuntimeException $e) {
    // caught locally — the global handler never runs
}

throw new RuntimeException('nothing catches this'); // → global handler runs, then script ends

Nachdem der Handler zurückkehrt, wird die Ausführung nicht fortgesetzt — das Skript wird beendet. Der Handler ist also Ihre letzte Möglichkeit, den Fehler sauber zu protokollieren und anzuzeigen, nicht ein Mittel zur Wiederherstellung und Fortsetzung.

Signatur und Rückgabewert

set_exception_handler(?callable $callback): ?callable

• $callback — ein aufrufbares Objekt, das das geworfene Objekt als einziges Argument akzeptiert. Seit PHP 7 implementiert jede Ausnahme und jeder Fehler Throwable, daher sollte der Parameter als Throwable (nicht nur Exception) typisiert werden, um auch Error-Instanzen wie TypeError abzufangen.
• Gibt den zuvor registrierten Handler zurück (oder null, wenn keiner gesetzt war), den Sie aufbewahren können, um ihn später wiederherzustellen. Die Übergabe von null entfernt den Handler.

Ausführbares Beispiel

Das folgende Skript registriert einen Handler, löst ihn mit einer unbehandelten Ausnahme aus und gibt eine formatierte Meldung aus. Es schreibt über error_log() ohne Ziel in die Standardfehlerausgabe und ist daher vollständig portabel:

<?php

function appExceptionHandler(Throwable $e): void
{
    $message = sprintf(
        "Uncaught %s: %s in %s on line %d",
        get_class($e),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    );

    error_log($message);            // goes to the SAPI error log / stderr
    echo "Something went wrong.\n"; // user-facing message
}

set_exception_handler('appExceptionHandler');

throw new RuntimeException('Database is unreachable');

Ausgabe (die error_log-Zeile geht an stderr, das echo an stdout):

Something went wrong.

mit einer Zeile wie Uncaught RuntimeException: Database is unreachable in /path/to/script.php on line 19 im Fehlerprotokoll.

Was er NICHT behandelt

set_exception_handler() fängt nur unbehandelte Ausnahmen ab. Er fängt nicht ab:

• Schwerwiegende Fehler, Parse-Fehler oder Warnungen — diese werden durch set_error_handler() (für abfangbare Fehler) oder register_shutdown_function() (für schwerwiegende Fehler) verarbeitet.
• Ausnahmen, die bereits von einem lokalen try/catch abgefangen wurden.

Für Nicht-Ausnahme-Fehler wie Warnungen und Hinweise registrieren Sie einen separaten Handler mit set_error_handler().

Den vorherigen Handler wiederherstellen

restore_exception_handler() setzt auf den Handler zurück, der vor Ihrem letzten set_exception_handler()-Aufruf aktiv war. Verwenden Sie ihn, wenn ein benutzerdefinierter Handler nur auf einen bestimmten Codeblock angewendet werden soll:

<?php

set_exception_handler(function (Throwable $e) {
    echo "Custom: {$e->getMessage()}\n";
});

// ... code that should use the custom handler ...

restore_exception_handler(); // back to the default behavior

Wichtig: Ihr Handler darf keine neue Ausnahme werfen. Wenn er das tut, kann PHP sie nicht erneut verarbeiten und löst stattdessen einen schwerwiegenden Fehler aus.

Best Practices für die Verwendung von set_exception_handler

Bei der Verwendung von set_exception_handler sollten Sie einige Best Practices befolgen, um sicherzustellen, dass Ihre Anwendung Fehler effektiv behandelt:

1. Typisieren Sie den Parameter des Handlers als Throwable, damit er sowohl Exception- als auch Error-Untertypen abfängt (PHP 7+).
2. Stellen Sie sicher, dass der Handler niemals eine neue Ausnahme wirft — das löst einen nicht behebaren schwerwiegenden Fehler aus.
3. Protokollieren Sie genügend Kontext zur Diagnose des Fehlers: Ausnahme-Klasse, Meldung, Datei, Zeile und den Stack-Trace aus $e->getTraceAsString().
4. Halten Sie die benutzerfreundliche Meldung allgemein; geben Sie in der Produktion niemals Stack-Traces oder Meldungen an Endbenutzer weiter.
5. Registrieren Sie den Handler so früh wie möglich (z. B. in einer Bootstrap-Datei), damit er die gesamte Anfrage abdeckt.
6. Kombinieren Sie ihn mit set_error_handler() und register_shutdown_function(), um auch Warnungen, Hinweise und schwerwiegende Fehler abzudecken.
7. Verwenden Sie restore_exception_handler(), um zum vorherigen Handler zurückzukehren, wenn ein benutzerdefinierter Handler auf einen Codeblock beschränkt sein soll.

Fazit

set_exception_handler() bietet Ihnen einen einzigen Ort, um jede unbehandelte Ausnahme in einer Anwendung zu verarbeiten — und wandelt einen rohen schwerwiegenden Fehler in konsistentes Logging und eine saubere benutzerfreundliche Meldung um. Beachten Sie seine Grenzen: Er wird nur für unbehandelte Ausnahmen ausgeführt, die Ausführung wird danach gestoppt, und der Handler selbst darf niemals werfen. Kombinieren Sie ihn mit set_error_handler() für Warnungen, trigger-error für benutzerdefinierte Fehlersignale und restore_exception_handler() für bereichsbezogene Behandlung, um robuste Fehlerberichterstattung aufzubauen.

Übung