filter_input_array()

Introduzione

filter_input_array() filtra un intero gruppo di input esterno — ogni campo di una richiesta $_GET o $_POST — in una singola chiamata, invece di estrarre i valori dai superglobali uno alla volta. Si fornisce una definizione che mappa ogni campo atteso a un filtro (validare o sanificare) e restituisce un array di valori puliti e verificati per tipo.

Questa pagina tratta la sintassi, come leggere il risultato (la differenza tra false, null e una chiave mancante), come allegare opzioni e flag ai singoli campi e come filter_input_array() si confronta con le sue funzioni sorelle per valori singoli e array arbitrari.

Per il quadro generale dell'estensione filter di PHP, consulta PHP Filters e PHP Advanced Filters.

Sintassi

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

Valore restituito:

• Un array di valori filtrati in caso di successo.
• false se $type non è valido.
• null se la sorgente di input richiesta non ha dati (e $add_empty è false).

La parte fondamentale è la lettura delle singole voci, non del valore di ritorno complessivo:

Un esempio autonomo

filter_input_array() legge dalle sorgenti reali INPUT_POST / INPUT_GET, che esistono solo durante una richiesta web. Per dimostrare le definizioni di filtro in modo eseguibile dalla riga di comando, lo snippet qui sotto usa filter_var_array() — accetta esattamente la stessa definizione $filters e applica lo stesso motore, quindi l'output è identico a quello che filter_input_array(INPUT_POST, $filters) produrrebbe per quei dati.

<?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);

Output:

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

Si noti che name è stato sanificato (i tag sono stati sottoposti a escape) mentre age ed email sono stati validati (restituiti rispettivamente come vero int e stringa verificata). Un campo non elencato in $filters viene eliminato completamente dal risultato.

Gestione dei campi non validi e mancanti

Poiché una validazione fallita restituisce false e un campo mancante restituisce null, non bisogna mai presumere che ogni voce sia utilizzabile. Verificare prima di fidarsi dei dati:

<?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);

Output:

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

print_r non mostra nulla dopo le chiavi perché age ed email sono false (non validi) e missing è null (assente). Nel codice reale, distinguerli esplicitamente:

<?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']}.";
}

Opzioni e flag per campo

Invece di una costante filtro semplice, un campo può essere un array annidato con le chiavi filter, options e flags — è qui che la funzione diventa potente. Usare options per cose come un intervallo di interi e il flag FILTER_REQUIRE_ARRAY quando un campo arriva come array (es. una selezione multipla o 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));

Output:

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

)

age è false perché 200 è fuori dall'intervallo 0–120, e ogni elemento di tags è stato sanificato singolarmente grazie a FILTER_REQUIRE_ARRAY.

Confronto con le funzioni correlate

Usare filter_input_array() quando i dati si trovano in $_GET/$_POST/ecc.; usare filter_var_array() quando si ha già l'array in una variabile.

Compatibilità con le versioni di PHP

FILTER_SANITIZE_STRING è stato deprecato in PHP 8.1 e rimosso in PHP 8.2. Per la sanificazione delle stringhe in PHP moderno, usare FILTER_SANITIZE_FULL_SPECIAL_CHARS (come negli esempi precedenti) oppure, per la validazione, un filtro dedicato come FILTER_VALIDATE_EMAIL.

Perché usarlo

• Sicurezza. Filtrare l'intera richiesta in un unico posto impedisce che valori non validati si infiltrino nelle query o nel markup. Abbinarlo a form validation e alle prepared statement.
• Leggibilità. La definizione $filters funge da schema per l'input atteso, separando le regole di validazione dalla logica di business.
• Coerenza. Ogni campo passa attraverso lo stesso motore collaudato, quindi non è necessario scrivere manualmente controlli isset() + is_numeric() per ogni campo.

Vedi anche PHP Superglobals per capire da dove proviene questo input.

Pratica