filter_var_array()

Introdução

O PHP oferece uma série de funções integradas para filtrar e validar dados de entrada do usuário. Uma dessas funções é filter_var_array(), que aplica filtros a várias variáveis de uma só vez, em vez de chamar filter_var() repetidamente. Ela é a principal responsável pelo processamento limpo de formulários: você descreve as regras para cada campo em um único array, passa os dados brutos e obtém de volta um resultado totalmente validado e sanitizado.

Este capítulo aborda a sintaxe, as três formas de definir filtros, como o sinalizador $add_empty se comporta, como ler o valor de retorno e as armadilhas mais comuns — com exemplos executáveis.

Sintaxe

A sintaxe de filter_var_array() é a seguinte:

A sintaxe PHP de filter_var_array()

filter_var_array ( array $data , mixed $definition [, bool $add_empty = true ] ) : mixed

A função retorna o array filtrado em caso de sucesso, ou false em caso de falha (por exemplo, se $data não for um array).

As três formas de definir filtros

O parâmetro $definition é o coração desta função. Ele pode assumir três formas.

1. Um filtro para todos os valores — passe uma única constante de filtro:

<?php
$data = ['a' => '1', 'b' => 'not-a-number', 'c' => '42'];
$result = filter_var_array($data, FILTER_VALIDATE_INT);
print_r($result);

Saída — valores que não passam no filtro tornam-se false:

Array
(
    [a] => 1
    [b] =>
    [c] => 42
)

2. Um mapa de filtro por chave — mapeie cada chave para sua própria constante de filtro:

<?php
$data = [
    'name'  => '  John  ',
    'age'   => '30',
    'email' => '[email protected]',
];

$definition = [
    'name'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
    'age'   => FILTER_VALIDATE_INT,
    'email' => FILTER_VALIDATE_EMAIL,
];

print_r(filter_var_array($data, $definition));

Array
(
    [name] =>   John  
    [age] => 30
    [email] => [email protected]
)

3. Um array por chave com filtro, sinalizadores e opções — para controle refinado, mapeie uma chave para um array que especifica o filter, além de flags e options:

<?php
$data = ['age' => '150', 'tags' => ['php', 'mysql']];

$definition = [
    'age' => [
        'filter'  => FILTER_VALIDATE_INT,
        'options' => ['min_range' => 0, 'max_range' => 120],
    ],
    'tags' => [
        'filter' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
        'flags'  => FILTER_REQUIRE_ARRAY,
    ],
];

var_dump(filter_var_array($data, $definition));

array(2) {
  ["age"]=>
  bool(false)
  ["tags"]=>
  array(2) {
    [0]=>
    string(3) "php"
    [1]=>
    string(5) "mysql"
  }
}

age é false porque 150 está fora do intervalo 0–120, e FILTER_REQUIRE_ARRAY instrui o filtro a tratar tags como um array e sanitizar cada elemento.

Uso com entrada de formulário

No código real, o array $data geralmente é uma superglobal como $_POST. A mesma definição que você acabou de ver aplica as regras e armazena os valores limpos em $result:

Exemplo de filter_var_array() em PHP

<?php

$filters = [
    'name'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
    'age'   => FILTER_VALIDATE_INT,
    'email' => FILTER_VALIDATE_EMAIL,
];

// $add_empty = false skips keys missing from $_POST instead of adding them as null
$result = filter_var_array($_POST, $filters, false);

if ($result === false || $result['email'] === false) {
    // Handle missing or invalid input
    echo 'Please correct the form.';
} else {
    // $result now holds clean, validated values
}

Observe que uma validação falha produz false para aquela chave, enquanto a função só retorna false globalmente quando o próprio $data é inválido. Sempre inspecione ambos. Para filtrar $_POST ou $_GET diretamente do fluxo de entrada, consulte o closely relacionado filter_input_array().

Nota: FILTER_SANITIZE_STRING foi removido no PHP 8.0. Use FILTER_SANITIZE_FULL_SPECIAL_CHARS em vez disso.

Benefícios

Aplicar filter_var_array() aumenta a segurança e a confiabilidade da sua aplicação PHP ao processar muitas variáveis em uma única chamada. Validar a entrada antes de processá-la garante que sua aplicação aceite apenas dados esperados, reduzindo o risco de injeção e bugs causados por dados malformados. Manter as regras em um array $definition declarativo também separa a validação da lógica de negócios, tornando os scripts mais modulares e fáceis de manter.

Conclusão

filter_var_array() é a forma eficiente de validar e sanitizar um conjunto inteiro de variáveis de uma vez. Escolha a forma de definição que melhor se adapta à sua necessidade — um filtro para todos, um mapa por chave ou arrays de opções por chave — e sempre verifique se há false por campo. Para aprofundar-se, leia a visão geral dos filtros PHP e o capítulo de validação de formulários PHP.

Prática