Filter\FilterException — Klasse · PHP-Referenz

Signatur

class FilterException extends RuntimeException

Beschreibung

Filter\FilterException ist die gemeinsame Basisklasse für alle Ausnahmen, die von der PHP-Filter-Erweiterung ausgelöst werden. Sie erweitert RuntimeException und ermöglicht es, alle filterbezogenen Fehler zentral abzufangen, ohne jede einzelne Unterklasse separat behandeln zu müssen.

Ab PHP 8.4 wirft die Filter-Erweiterung unter bestimmten Umständen Ausnahmen anstatt lediglich false oder null zurückzugeben. Indem man Filter\FilterException im catch-Block verwendet, lassen sich sämtliche filterspezifischen Ausnahmen einheitlich behandeln.

Eigene Ausnahmen, die von Filteroperationen abgeleitet werden sollen, können von dieser Klasse erben. Das erleichtert die Fehlerbehandlung in größeren Anwendungen, die die Filter-Erweiterung intensiv nutzen, da ein einziger catch-Block für alle filterbezogenen Probleme ausreicht.

Beispiele

Abfangen einer filterbezogenen Ausnahme

<?php
use Filter\FilterException;

try {
    // filter_var() kann in bestimmten Konfigurationen eine FilterException werfen
    $result = filter_var('ungültige-email', FILTER_VALIDATE_EMAIL, FILTER_NULL_ON_FAILURE);
    if ($result === null) {
        throw new FilterException('Die E-Mail-Adresse konnte nicht validiert werden.');
    }
    echo $result;
} catch (FilterException $e) {
    echo 'Filterfehler: ' . $e->getMessage();
}

Filterfehler: Die E-Mail-Adresse konnte nicht validiert werden.

Eigene Ausnahme von FilterException ableiten

<?php
use Filter\FilterException;

class UngueltigeEingabeException extends FilterException
{
    public function __construct(string $feld, string $wert)
    {
        parent::__construct(
            sprintf('Das Feld "%s" enthält einen ungültigen Wert: "%s"', $feld, $wert)
        );
    }
}

function validiereAlter(mixed $eingabe): int
{
    $alter = filter_var($eingabe, FILTER_VALIDATE_INT, [
        'options' => ['min_range' => 0, 'max_range' => 150],
    ]);
    if ($alter === false) {
        throw new UngueltigeEingabeException('alter', (string) $eingabe);
    }
    return $alter;
}

try {
    echo validiereAlter('abc');
} catch (FilterException $e) {
    echo 'Eingabefehler: ' . $e->getMessage();
}

Eingabefehler: Das Feld "alter" enthält einen ungültigen Wert: "abc"

// Wichtig · Fallstricke

Neu in PHP 8.4: Filter\FilterException wurde mit PHP 8.4 eingeführt. In älteren PHP-Versionen existiert diese Klasse nicht, und die Filter-Erweiterung kommuniziert Fehler ausschließlich über Rückgabewerte wie false oder null. Code, der diese Klasse verwendet, ist daher nicht abwärtskompatibel mit PHP < 8.4.

Da Filter\FilterException von RuntimeException erbt, kann sie auch in einem generischen catch (\RuntimeException $e)-Block abgefangen werden. Für eine präzise Fehlerbehandlung empfiehlt sich jedoch der spezifischere Typ.

Siehe auch

filter_var filter_input RuntimeException