Filter\FilterFailedException — Klasse · PHP-Referenz

Signatur

class FilterFailedException extends RuntimeException

Beschreibung

Filter\FilterFailedException ist eine spezialisierte Ausnahme, die geworfen wird, wenn eine Filteroperation nicht erfolgreich abgeschlossen werden kann. Sie erbt von RuntimeException und gehört zum Filter-Namespace, der mit PHP 8.0 eingeführt wurde.

Diese Exception tritt typischerweise auf, wenn ein Filter mit ungültigen Eingaben oder falschen Parametern aufgerufen wird und keine andere Möglichkeit besteht, den Fehler als Rückgabewert (false oder null) zu kommunizieren. Sie ermöglicht es, Filterfehler über den normalen Exception-Mechanismus von PHP sauber abzufangen und zu behandeln.

Im Gegensatz zu älteren Filterfunktionen wie filter_var(), die bei einem Fehler false oder null zurückgeben, bietet der objektorientierte Filter-Ansatz mit dieser Exception eine präzisere Fehlerbehandlung, da der Fehlerkontext über die Exception-Nachricht und den Stack-Trace zugänglich ist.

Um diese Exception abzufangen, sollte ein catch(Filter\FilterFailedException $e)-Block verwendet werden, oder es kann allgemein mit catch(RuntimeException $e) gearbeitet werden, wenn eine breitere Fehlerbehandlung gewünscht ist.

Beispiele

Abfangen einer FilterFailedException

<?php
use Filter\FilterFailedException;

try {
    // Beispiel: Einen Filter mit ungültiger Eingabe ausführen,
    // der eine FilterFailedException auslöst
    $filter = new \Filter\IntFilter();
    $result = $filter->filter('das-ist-keine-zahl');
} catch (FilterFailedException $e) {
    echo 'Filterfehler: ' . $e->getMessage() . PHP_EOL;
    echo 'Code: ' . $e->getCode() . PHP_EOL;
} catch (\RuntimeException $e) {
    echo 'Allgemeiner Laufzeitfehler: ' . $e->getMessage() . PHP_EOL;
}

Filterfehler: Filter operation failed.

Eigene Fehlerbehandlung mit FilterFailedException

<?php
use Filter\FilterFailedException;

function filterSafeInt(mixed $value): int {
    try {
        $filter = new \Filter\IntFilter();
        return $filter->filter($value);
    } catch (FilterFailedException $e) {
        // Standardwert zurückgeben, wenn Filter fehlschlägt
        error_log('Filterfehler für Wert: ' . var_export($value, true) . ' – ' . $e->getMessage());
        return 0;
    }
}

$wert = filterSafeInt('keine-zahl');
echo $wert; // gibt 0 aus

$wert2 = filterSafeInt(42);
echo $wert2; // gibt 42 aus

0 42

// Wichtig · Fallstricke

Hinweis zur Verfügbarkeit: Der Filter-Namespace und dessen Klassen sind Teil eines neueren, objektorientierten Filter-APIs in PHP. Stellen Sie sicher, dass die entsprechende Erweiterung installiert und aktiviert ist. In älteren PHP-Versionen (vor 8.0) steht diese Klasse nicht zur Verfügung.

Abwärtskompatibilität: Wenn Code sowohl auf PHP 7.x als auch auf PHP 8.x laufen soll, sollte auf die prozedurale API (filter_var(), filter_input()) zurückgegriffen werden, da Filter\FilterFailedException dort nicht existiert.

Vererbungshierarchie: Da FilterFailedException von RuntimeException erbt, kann sie auch mit einem allgemeinen catch(\Exception $e)-Block abgefangen werden, was jedoch weniger präzise ist und nicht empfohlen wird.

Siehe auch

filter_var filter_input RuntimeException FILTER_VALIDATE_INT