filter_input_array()

Einführung

filter_input_array() filtert einen ganzen Stapel externer Eingaben — jedes Feld einer $_GET- oder $_POST-Anfrage — in einem einzigen Aufruf, anstatt Werte einzeln aus den Superglobals herauszuziehen. Sie übergeben eine Definition, die jedes erwartete Feld einem Filter (Validierung oder Bereinigung) zuordnet, und die Funktion gibt ein array mit bereinigten, typgeprüften Werten zurück.

Diese Seite behandelt die Syntax, wie das Ergebnis zu lesen ist (den Unterschied zwischen false, null und einem fehlenden Schlüssel), wie Optionen und Flags an einzelne Felder angehängt werden, und wie filter_input_array() im Vergleich zu ihren Geschwisterfunktionen für Einzelwerte und beliebige Arrays steht.

Einen größeren Überblick über PHP's Filter-Erweiterung finden Sie unter PHP Filters und PHP Advanced Filters.

Syntax

filter_input_array(int $type, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null

Rückgabewert:

• Ein array gefilterter Werte bei Erfolg.
• false, wenn $type ungültig ist.
• null, wenn die angeforderte Eingabequelle überhaupt keine Daten enthält (und $add_empty false ist).

Der entscheidende Teil ist das Lesen einzelner Einträge, nicht des allgemeinen Rückgabewerts:

Ein eigenständiges Beispiel

filter_input_array() liest aus den echten INPUT_POST- / INPUT_GET-Quellen, die nur während einer Web-Anfrage existieren. Um die Filterdefinitionen auf eine Weise zu demonstrieren, die Sie auf der Kommandozeile ausführen können, verwendet das folgende Snippet filter_var_array() — es akzeptiert exakt dieselbe $filters-Definition und wendet dieselbe Engine an, sodass die Ausgabe identisch mit dem ist, was filter_input_array(INPUT_POST, $filters) für diese Daten erzeugen würde.

<?php

// In a real request this array would be $_POST.
$input = [
    'name'  => '<b>Jane</b>',
    'age'   => '30',
    'email' => '[email protected]',
];

$filters = [
    'name'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS, // sanitize: escape HTML
    'age'   => FILTER_VALIDATE_INT,                // validate: must be an int
    'email' => FILTER_VALIDATE_EMAIL,              // validate: must be an email
];

$data = filter_var_array($input, $filters);
// In a controller you would write:
// $data = filter_input_array(INPUT_POST, $filters);

print_r($data);

Ausgabe:

Array
(
    [name] => <b>Jane</b>
    [age] => 30
    [email] => [email protected]
)

Beachten Sie, dass name bereinigt wurde (die Tags wurden escaped), während age und email validiert wurden (als echte int- bzw. überprüfte string-Werte zurückgegeben). Ein Feld, das nicht in $filters aufgeführt ist, wird vollständig aus dem Ergebnis entfernt.

Ungültige und fehlende Felder behandeln

Da eine fehlgeschlagene Validierung false und ein fehlendes Feld null ergibt, sollten Sie niemals davon ausgehen, dass jeder Eintrag verwendbar ist. Prüfen Sie vor der Verwendung der Daten:

<?php

$input = [
    'age'   => 'not-a-number',
    'email' => 'bad-email',
];

$filters = [
    'age'     => FILTER_VALIDATE_INT,
    'email'   => FILTER_VALIDATE_EMAIL,
    'missing' => FILTER_VALIDATE_INT, // declared, but absent from input
];

$data = filter_var_array($input, $filters);

print_r($data);

Ausgabe:

Array
(
    [age] =>
    [email] =>
    [missing] =>
)

print_r zeigt nach den Schlüsseln nichts an, weil age und email false (ungültig) sind und missing null (nicht vorhanden) ist. Im echten Code sollten Sie explizit unterscheiden:

<?php
if ($data['age'] === false) {
    echo "Age is not a valid integer.";
} elseif ($data['age'] === null) {
    echo "Age was not submitted.";
} else {
    echo "Age is {$data['age']}.";
}

Optionen und Flags pro Feld

Anstatt einer einfachen Filterkonstante kann ein Feld ein verschachteltes array mit den Schlüsseln filter, options und flags sein — hier wird die Funktion wirklich leistungsfähig. Verwenden Sie options für Dinge wie einen Ganzzahlbereich, und das FILTER_REQUIRE_ARRAY-Flag, wenn ein Feld als array ankommt (z. B. bei einer Mehrfachauswahl oder name="tags[]").

<?php

$input = [
    'age'  => '200',
    'tags' => ['<a>', '<b>'],
];

$args = [
    'age' => [
        'filter'  => FILTER_VALIDATE_INT,
        'options' => ['min_range' => 0, 'max_range' => 120],
    ],
    'tags' => [
        'filter' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
        'flags'  => FILTER_REQUIRE_ARRAY, // apply the filter to each element
    ],
];

print_r(filter_var_array($input, $args));

Ausgabe:

Array
(
    [age] =>
    [tags] => Array
        (
            [0] => <a>
            [1] => <b>
        )

)

age ist false, weil 200 außerhalb des Bereichs 0–120 liegt, und jedes Element von tags wurde dank FILTER_REQUIRE_ARRAY einzeln bereinigt.

Vergleich mit verwandten Funktionen

Verwenden Sie filter_input_array(), wenn die Daten in $_GET/$_POST/usw. liegen; verwenden Sie filter_var_array(), wenn Sie das array bereits als Variable vorliegen haben.

PHP-Versionskompatibilität

FILTER_SANITIZE_STRING wurde in PHP 8.1 als veraltet markiert und in PHP 8.2 entfernt. Für die string-Bereinigung in modernem PHP verwenden Sie FILTER_SANITIZE_FULL_SPECIAL_CHARS (wie in den Beispielen oben) oder, zur Validierung, einen dedizierten Filter wie FILTER_VALIDATE_EMAIL.

Warum es verwenden

• Sicherheit. Das Filtern der gesamten Anfrage an einem Ort verhindert, dass unvalidierte Werte in Abfragen oder Markup gelangen. Kombinieren Sie es mit Formularvalidierung und Prepared Statements.
• Lesbarkeit. Die $filters-Definition dient als Schema für die erwartete Eingabe und trennt Validierungsregeln von der Geschäftslogik.
• Konsistenz. Jedes Feld durchläuft dieselbe geprüfte Engine, sodass Sie nicht pro Feld manuell isset() + is_numeric()-Prüfungen schreiben müssen.

Siehe auch PHP Superglobals für den Ursprung dieser Eingaben.

Übungen