Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung

### Beschreibung

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

Setzt eine benutzerdefinierte Funktion (`callback`), um Fehler in einem Skript zu behandeln.

Mit dieser Funktion können während der Laufzeit benutzerdefinierte Fehlerbehandlungen erstellt werden, beispielsweise in Anwendungen, die bei einem kritischen Fehler die Löschung von Daten bzw. Dateien erfordert, oder wenn es nötig ist, unter bestimmten Bedingungen (mit der Funktion trigger_error()) eine Fehlermeldung zu generieren.

Es ist unbedingt zu beachten, dass auf diese Weise die standardmäßige PHP-Fehlerbehandlung für die durch `error_levels` angegebenen Fehlertypen vollkommen umgangen wird, außer wenn die Callback-Funktion `false` zurückgibt. Die Einstellungen der Funktion error_reporting() haben keine Auswirkung und die Fehlerbehandlungsroutine wird ohne Rücksicht darauf aufgerufen, es ist jedoch immer noch möglich, den aktuellen Wert von error_reporting zu lesen und entsprechend zu handeln.

Es ist auch zu beachten, dass die Fehlerbehandlung dafür zuständig ist, bei Bedarf exit() aufzurufen, um die Ausführung des Skripts zu beenden. Nach der Funktion für die Fehlerbehandlung wird die Ausführung des Skripts bei der Anweisung fortgesetzt, die auf die Fehler verursachende Anweisung folgt.

Die folgenden Fehlertypen können nicht von einer benutzerdefinierten Funktion behandelt werden: `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR` und `E_COMPILE_WARNING` unabhängig davon, wo sie ausgelöst wurden, und die meisten `E_STRICT`, die in der Datei ausgelöst werden, in der set_error_handler() aufgerufen wird.

Falls Fehler auftreten, bevor das Skript ausgeführt wird (z. B. beim Hochladen von Dateien), kann eine benutzerdefinierte Fehlerbehandlung nicht aufgerufen werden, weil sie zu diesem Zeitpunkt noch nicht registriert ist.

### Parameter-Liste

`callback`

  Falls `null` übergeben wird, wird der Handler auf seinen Standardwert zurückgesetzt. Andernfalls ist der Handler ein Callback mit der folgenden Signatur:

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    Dem erstem Parameter, `errno`, wird der Schweregrad des ausgelösten Fehlers als Integer übergeben.
  `errstr`
    Dem zweiten Parameter, `errstr`, wird die Fehlermeldung als String übergeben.
  `errfile`
    Wenn der Callback einen dritten Parameter akzeptiert, nämlich `errfile`, wird der Dateiname, in dem der Fehler aufgetreten ist, als String übergeben.
  `errline`
    Wenn der Callback einen vierten Parameter akzeptiert, nämlich `errline`, wird die Zeilennummer, in der der Fehler aufgetreten ist, als Integer übergeben.
  `errcontext`
    Wenn der Callback einen fünften Parameter akzeptiert, nämlich `errcontext`, wird ihm ein Array übergeben, das auf die aktive Symboltabelle zu dem Punkt zeigt, an dem der Fehler auftrat. Mit anderen Worten: `errcontext` enthält ein Array mit allen Variablen, die im fehlerauslösenden Bereich existierten. Benutzerdefinierte Fehlerbehandlungen dürfen den Fehlerkontext nicht verändern.
    Warnung

    Dieser Parameter ist von PHP 7.2.0 an MISSBILLIGT und wurde in PHP 8.0.0 ENTFERNT. Wenn die Funktion diesen Parameter ohne Vorgabe definiert, wird beim Aufruf der Funktion der Fehler "too few arguments" (zu wenig Parameter) ausgelöst.

  Falls diese Funktion `false` zurückgibt, wird mit der normalen Fehlerbehandlung fortgesetzt.

`error_levels`

  Kann wie die php.ini-Konfigurationseinstellung error_reporting, die bestimmt, welche Fehler angezeigt werden, zum Maskieren des Aufrufs der `callback`-Funktion verwendet werden. Wird diese Maske nicht gesetzt, wird der `callback` unabhängig von der Einstellung error_reporting bei jedem Fehler aufgerufen.

### Rückgabewerte

Gibt die zuvor definierte Fehlerbehandlungsroutine (falls eine definiert wurde) als callable zurück. Wenn der eingebaute Errorhandler verwendet wurde, wird `null` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `errcontext` wurde entfernt und wird nicht mehr an Benutzer-Callbacks übergeben.
7.2.0 | `errcontext` wurde missbilligt. Die Verwendung dieses Parameters erzeugt nun einen `E_DEPRECATED`-Hinweis.

### Beispiele

Beispiel #1 Fehlerbehandlung mit set_error_handler() und trigger_error()

Das untenstehende Beispiel zeigt die Behandlung von internen Ausnahmen, indem Fehler ausgelöst und durch eine benutzerdefinierte Funktion behandelt werden:

    <?php
    // Fehlerbehandlungsfunktion
    function myErrorHandler($fehlercode, $fehlertext, $fehlerdatei, $fehlerzeile)
    {
        if (!(error_reporting() & $fehlercode)) {
            // Dieser Fehlercode ist nicht in error_reporting enthalten
            return false;
        }

        // $fehlertext muss möglicherweise maskiert werden:
        $fehlertext = htmlspecialchars($fehlertext);

        switch ($fehlercode) {
        case E_USER_ERROR:
            echo "<b>Mein FEHLER</b> [$fehlercode] $fehlertext<br />\n";
            echo "  Fataler Fehler in Zeile $fehlerzeile in der Datei $fehlerdatei";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Abbruch...<br />\n";
            break;

        case E_USER_WARNING:
            echo "<b>Meine WARNUNG</b> [$fehlercode] $fehlertext<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>Mein HINWEIS</b> [$fehlercode] $fehlertext<br />\n";
            break;

        default:
            echo "Unbekannter Fehlertyp: [$fehlercode] $fehlertext<br />\n";
            break;
        }

        /* Damit die PHP-interne Fehlerbehandlung nicht ausgeführt wird */
        return true;
    }

    // Funktion zum Test der Fehlerbehandlung
    function logarithmisch_skalieren($vektor, $skalierung)
    {
        if (!is_numeric($skalierung) || $skalierung <= 0) {
            trigger_error("log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung", E_USER_ERROR);
        }

        if (!is_array($vektor)) {
            trigger_error("Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vektor as $pos => $wert) {
            if (!is_numeric($wert)) {
                trigger_error("Der Wert an Position $pos ist keine Zahl, verwende 0 (Null)", E_USER_NOTICE);
                $wert = 0;
            }
            $temp[$pos] = log($skalierung) * $wert;
        }

        return $temp;
    }

    // auf die benutzerdefinierte Fehlerbehandlung umstellen
    $alter_error_handler = set_error_handler("myErrorHandler");

    // ein paar Fehler auslösen, zuerst wird ein gemischtes Array mit einem
    // nichtnumerischen Eintrag definiert
    echo "Vektor a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // ein zweites Array erzeugen
    echo "----\nVektor b - ein Hinweis (b = log(PI) * a)\n";
    /* Der Wert an Position $pos ist keine Zahl, verwende 0 (Null) */
    $b = logarithmisch_skalieren($a, M_PI);
    print_r($b);

    // das gibt Ärger: statt eines Arrays wird eine Zeichenkette übergeben
    echo "----\nVektor c - eine Warnung\n";
    /* Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet */
    $c = logarithmisch_skalieren("kein Array", 2.3);
    var_dump($c); // NULL

    // dies ist ein kritischer Fehler: log ist für Null oder negative Werte
    // nicht definiert
    echo "----\nVektor d - fataler Fehler\n";
    /* log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung */
    $d = logarithmisch_skalieren($a, -2.5);
    var_dump($d); // wird nie erreicht
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Vektor a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    Vektor b - ein Hinweis (b = log(PI) * a)
    <b>Mein HINWEIS</b> [1024] Der Wert an Position 2 ist keine Zahl, verwende 0 (Null)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    Vektor c - eine Warnung
    <b>Meine WARNUNG</b> [512] Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet<br />
    NULL
    ----
    Vektor d - fataler Fehler
    <b>Mein FEHLER</b> [256] log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = -2.5<br />
      Fataler Fehler in Zeile 35 in der Datei trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
    Abbruch...<br />

### Siehe auch

- ErrorException
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- get_error_handler() - Gets the user-defined error handler function
- trigger_error() - Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
- Errorlevel-Konstanten

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open