filter_input_array()

Introdução

filter_input_array() filtra um lote inteiro de entradas externas — todos os campos de uma requisição $_GET ou $_POST — em uma única chamada, em vez de extrair valores das superglobais um por um. Você fornece uma definição que mapeia cada campo esperado para um filtro (validar ou sanitizar), e ela retorna um array de valores limpos e verificados por tipo.

Esta página abrange a sintaxe, como ler o resultado (a diferença entre false, null e uma chave ausente), como anexar opções e flags a campos individuais e como filter_input_array() se compara aos seus irmãos de valor único e de array arbitrário.

Para uma visão mais ampla da extensão de filtros do PHP, veja PHP Filters e PHP Advanced Filters.

Sintaxe

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

Valor de retorno:

• Um array de valores filtrados em caso de sucesso.
• false se $type for inválido.
• null se a fonte de entrada solicitada não tiver nenhum dado (e $add_empty for false).

A parte crucial é a leitura de entradas individuais, não o valor de retorno geral:

Um exemplo autocontido

filter_input_array() lê das fontes reais INPUT_POST / INPUT_GET, que só existem durante uma requisição web. Para demonstrar as definições de filtro de uma forma que você possa executar na linha de comando, o trecho abaixo usa filter_var_array() — ele aceita exatamente a mesma definição $filters e aplica o mesmo mecanismo, portanto a saída é idêntica ao que filter_input_array(INPUT_POST, $filters) produziria para esses dados.

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

Saída:

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

Observe que name foi sanitizado (as tags foram escapadas) enquanto age e email foram validados (retornados como um int real e uma string verificada). Um campo que não está listado em $filters é completamente descartado do resultado.

Tratando campos inválidos e ausentes

Como uma validação falha resulta em false e um campo ausente resulta em null, nunca presuma que todas as entradas são utilizáveis. Verifique antes de confiar nos dados:

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

Saída:

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

print_r não mostra nada após as chaves porque age e email são false (inválidos) e missing é null (ausente). No código real, distinga-os explicitamente:

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

Opções e flags por campo

Em vez de uma constante de filtro simples, um campo pode ser um array aninhado com as chaves filter, options e flags — é aqui que a função se torna poderosa. Use options para coisas como um intervalo de inteiros, e a flag FILTER_REQUIRE_ARRAY quando um campo chega como um array (por exemplo, um multi-select ou 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));

Saída:

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

)

age é false porque 200 está fora do intervalo 0–120, e cada elemento de tags foi sanitizado individualmente graças ao FILTER_REQUIRE_ARRAY.

Como se compara a funções relacionadas

Use filter_input_array() quando os dados estiverem em $_GET/$_POST/etc.; use filter_var_array() quando você já tiver o array em uma variável.

Compatibilidade com versões do PHP

FILTER_SANITIZE_STRING foi descontinuado no PHP 8.1 e removido no PHP 8.2. Para sanitização de strings no PHP moderno, use FILTER_SANITIZE_FULL_SPECIAL_CHARS (como nos exemplos acima) ou, para validação, um filtro dedicado como FILTER_VALIDATE_EMAIL.

Por que usá-la

• Segurança. Filtrar a requisição inteira em um único lugar evita que valores não validados vazem para consultas ou marcação. Combine com validação de formulários e instruções preparadas.
• Legibilidade. A definição $filters funciona como um esquema para a entrada esperada, separando as regras de validação da lógica de negócios.
• Consistência. Cada campo passa pelo mesmo mecanismo testado, então você não precisa escrever verificações isset() + is_numeric() manualmente para cada campo.

Veja também PHP Superglobals para entender de onde vem essa entrada.

Prática