trigger_error()

Einführung

trigger_error() ermöglicht es Ihrem eigenen Code, eine PHP-Fehlermeldung auszulösen – auf dieselbe Weise, wie die Engine eingebaute Fehler erzeugt. Dies ist der Standardweg, um anzuzeigen, dass eine Funktion falsch aufgerufen wurde – ein fehlendes Argument, ein Wert außerhalb des gültigen Bereichs, ein veralteter Aufruf – ohne eine Exception zu werfen oder ein ad-hoc-echo auszugeben. Da die Meldung durch PHPs normale Fehler-Pipeline fließt, berücksichtigt sie error_reporting, kann automatisch protokolliert werden und kann von einem benutzerdefinierten Fehler-Handler abgefangen werden.

Diese Seite erklärt, was trigger_error() tut, seine Syntax und Fehlerstufen, und zeigt ein ausführbares Beispiel für jede Stufe sowie einen praktischen Anwendungsfall zur Eingabevalidierung.

Was ist die Funktion trigger_error()?

trigger_error() löst einen benutzerseitigen Fehler aus – einen Fehler, den Ihr Programm absichtlich erzeugt, im Gegensatz zu einem, den die PHP-Engine selbst auslöst. Wenn Sie die Funktion aufrufen, verhält sich PHP genau so, als hätte es diesen Fehler selbst erkannt: Es wendet die aktuelle error_reporting-Maske an, sendet die Meldung an den aktiven Fehler-Handler (oder den Standardhandler) und beendet das Skript möglicherweise je nach Fehlerstufe.

Zwei Dinge werden leicht falsch verstanden:

• trigger_error() löst einen Fehler aus, keine Exception. Er wird nicht von try/catch abgefangen, es sei denn, ein benutzerdefinierter Handler wandelt ihn in eine Exception um (ein gängiges Muster, das weiter unten gezeigt wird).
• Die Funktion gibt immer false zurück, daher ist return trigger_error(...) selten das, was Sie beabsichtigen.

Syntax von trigger_error()

trigger_error(string $message, int $error_level = E_USER_NOTICE): bool

Die Fehlerstufe muss eine der folgenden sein:

• E_USER_ERROR — ein fataler Fehler. Mit dem Standard-Handler stoppt er das Skript sofort. Mit einem benutzerdefinierten Handler läuft das Skript weiter, sofern der Handler es nicht stoppt (indem er false zurückgibt und PHP durchfallen lässt oder exit() aufruft).
• E_USER_WARNING — eine nicht-fatale Warnung. Das Skript läuft weiter.
• E_USER_NOTICE — eine informative Meldung. Das Skript läuft weiter. Dies ist der Standardwert.

Das Übergeben einer anderen Konstante (beispielsweise E_WARNING) löst eine eigene E_USER_WARNING aus und ignoriert Ihren Wert.

trigger_error() berücksichtigt die aktuelle error_reporting-Stufe: Ist die ausgelöste Stufe maskiert, wird nichts gemeldet. Ist also error_reporting(E_ALL & ~E_USER_NOTICE) gesetzt, wird ein von Ihnen ausgelöster Hinweis stillschweigend verworfen.

Hinweis für PHP 8.4+: Das Auslösen von E_USER_ERROR ist veraltet. Das Werfen einer Exception ist jetzt der empfohlene Weg, um einen fatalen benutzerseitigen Zustand zu signalisieren. Die anderen beiden Stufen werden weiterhin vollständig unterstützt.

Ein einfacher Hinweis mit dem Standard-Handler

Die minimale Verwendung von trigger_error() ist ein einzelner Aufruf. Mit PHPs Standard-Fehler-Handler und aktivierter Anzeige gibt er eine formatierte Zeile aus, und die Ausführung wird fortgesetzt (Hinweise sind nicht fatal):

<?php
echo "Before\n";
trigger_error("Something worth noting", E_USER_NOTICE);
echo "After\n";

Ausgabe (mit aktiviertem display_errors):

Before

Notice: Something worth noting in /path/to/script.php on line 3
After

Das Skript erreicht das abschließende echo, weil ein Hinweis die Ausführung nicht stoppt.

Die Stufen mit einem benutzerdefinierten Handler unterscheiden

Ein benutzerdefinierter Fehler-Handler gibt Ihnen volle Kontrolle darüber, wie jede Stufe dargestellt wird. Der Handler erhält die Stufennummer als $errno, sodass Sie sie einer Bezeichnung zuordnen und entscheiden können, was als Nächstes zu tun ist.

<?php
function custom_error_handler($errno, $errstr, $errfile, $errline) {
  $label = match ($errno) {
    E_USER_ERROR   => 'ERROR',
    E_USER_WARNING => 'WARNING',
    E_USER_NOTICE  => 'NOTICE',
    default        => 'UNKNOWN',
  };
  echo "[$label] $errstr (line $errline)\n";
  // Returning true tells PHP we handled it, so the default handler is skipped.
  return true;
}

set_error_handler("custom_error_handler");

trigger_error("Disk is almost full", E_USER_NOTICE);
trigger_error("Cache miss, falling back to DB", E_USER_WARNING);

echo "Script finished\n";

Ausgabe:

[NOTICE] Disk is almost full (line 16)
[WARNING] Cache miss, falling back to DB (line 17)
Script finished

Der Handler gibt true zurück, was PHP mitteilt, dass der Fehler behandelt wurde, sodass der Standard-Handler übersprungen wird und das Skript weiterläuft. Der E_USER_ERROR-Zweig ist der Vollständigkeit halber im match enthalten, aber beachten Sie, dass mit dem Standard-Handler ein E_USER_ERROR das Skript vor "Script finished" stoppen würde – und in PHP 8.4+ ist das Auslösen dieser Stufe veraltet.

Praktische Anwendung: Funktionsargumente validieren

Die häufigste reale Verwendung von trigger_error() ist der Schutz einer Funktion vor fehlerhaften Eingaben – das Ausgeben einer Warnung, wenn ein Aufrufer etwas Ungültiges übergibt, und das anschließende Zurückgeben eines sicheren Standardwerts:

<?php
function divide($a, $b) {
  if ($b == 0) {
    trigger_error("divide(): division by zero, returning 0", E_USER_WARNING);
    return 0;
  }
  return $a / $b;
}

echo divide(10, 2), "\n";   // 5
echo divide(10, 0), "\n";   // warning + 0

Ausgabe (mit aktiviertem display_errors):

5

Warning: divide(): division by zero, returning 0 in /path/to/script.php on line 4
0

Dieses Muster bewahrt den Stack-Trace und die Zeilennummer des Aufrufers in der Meldung, was es wesentlich einfacher macht, den fehlerhaften Aufruf zu finden, als ein einfaches echo.

Fehler in Exceptions umwandeln

Wenn Sie Probleme lieber mit try/catch behandeln möchten, kann ein benutzerdefinierter Handler einen ausgelösten Fehler in eine ErrorException umwandeln. Dies ist die Brücke zwischen PHPs Fehlersystem und seinem Exception-System:

<?php
set_error_handler(function ($errno, $errstr, $errfile, $errline) {
  throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
  trigger_error("Recoverable problem", E_USER_WARNING);
} catch (ErrorException $e) {
  echo "Caught: " . $e->getMessage() . "\n";
}

Ausgabe:

Caught: Recoverable problem

Da der Handler eine Exception wirft, erreicht die Warnung nie die Standard-Fehlerausgabe – sie wird stattdessen an Ihren catch-Block geliefert.

Häufige Fallstricke

• Es ist keine Exception. Ohne einen Handler, der eine Exception wirft, wird try/catch einen ausgelösten Fehler nicht abfangen.
• error_reporting kann ihn verbergen. Ist die Stufe maskiert, verschwindet Ihre Meldung ohne Hinweis. Prüfen Sie die aktuelle Stufe mit error_reporting().
• E_USER_ERROR ist in PHP 8.4+ veraltet. Werfen Sie stattdessen eine Exception (oder rufen Sie die() auf) für fatale benutzerseitige Bedingungen.
• Die Meldung wird bei 1024 Bytes abgeschnitten – halten Sie sie prägnant.

Fazit

trigger_error() ist der idiomatische Weg, um einen benutzerseitigen E_USER_NOTICE, E_USER_WARNING oder (veraltet) E_USER_ERROR auszulösen. Es leitet Ihre Meldungen in PHPs Standard-Pipeline ein, sodass sie error_reporting berücksichtigen, protokolliert werden können und von einem benutzerdefinierten Fehler-Handler abgefangen – oder in Exceptions umgewandelt werden können, wenn Sie try/catch-Semantik wünschen. Für neuen Code auf fataler Ebene bevorzugen Sie das Werfen von Exceptions gegenüber E_USER_ERROR.

Übung