PHP Filter

A extensão filter do PHP é a ferramenta nativa para verificar e limpar dados provenientes de fontes externas ao seu script — campos de formulário, query strings, cookies e cabeçalhos HTTP. Como esses dados são controlados pelo usuário (e às vezes por um invasor), você nunca deve confiar neles diretamente. Esta página explica a diferença entre validar e sanitizar, as principais funções (filter_var() e filter_input()), as constantes de filtro mais usadas e as armadilhas que costumam pegar as pessoas de surpresa.

Validar vs. sanitizar

A extensão filter realiza dois trabalhos distintos, e confundi-los é o erro mais comum:

• Validar — verifica se um valor corresponde a uma regra e retorna o valor caso corresponda, ou false caso contrário. Nunca altera o valor. Use filtros FILTER_VALIDATE_*.
• Sanitizar — remove ou escapa caracteres inválidos e retorna a string limpa. Nunca informa se a entrada estava "correta". Use filtros FILTER_SANITIZE_*.

Regra geral: valide para decidir se aceita a entrada, sanitize para torná-la segura de usar. Eles não são intercambiáveis — um e-mail sanitizado não é garantia de que o e-mail está bem formado.

filter_var() — filtrar uma única variável

filter_var() é a função principal. Ela recebe um valor, uma constante de filtro e opções opcionais:

filter_var(mixed $value, int $filter = FILTER_DEFAULT, array|int $options = 0): mixed

Validando

<?php
$email = "[email protected]";

if (filter_var($email, FILTER_VALIDATE_EMAIL)) {
    echo "Email is valid\n";
} else {
    echo "Email is invalid\n";
}

// Numbers, URLs and IPs work the same way:
var_dump(filter_var("42", FILTER_VALIDATE_INT));        // int(42)
var_dump(filter_var("not-a-number", FILTER_VALIDATE_INT)); // bool(false)
var_dump(filter_var("https://w3docs.com", FILTER_VALIDATE_URL)); // string

Saída:

Email is valid
int(42)
bool(false)
string(18) "https://w3docs.com"

Atenção: filtros de validação retornam false em caso de falha, mas 0 e "" também são falsy. filter_var("0", FILTER_VALIDATE_INT) retorna int(0), o que falha num if ingênuo. Compare com === false, ou passe FILTER_NULL_ON_FAILURE para que falhas se tornem null e você possa usar !== null.

Sanitizando

<?php
$dirty = "  john (doe)@exa<>mple.com  ";
echo filter_var($dirty, FILTER_SANITIZE_EMAIL), "\n"; // [email protected]

$comment = "<script>alert(1)</script>Hi";
echo filter_var($comment, FILTER_SANITIZE_SPECIAL_CHARS), "\n";

Saída:

[email protected]
<script>alert(1)</script>Hi

Passando opções e flags

Muitos filtros aceitam opções extras. Por exemplo, validar um inteiro apenas dentro de um intervalo:

<?php
$options = [
    "options" => ["min_range" => 1, "max_range" => 120],
];
var_dump(filter_var("130", FILTER_VALIDATE_INT, $options)); // bool(false)
var_dump(filter_var("25",  FILTER_VALIDATE_INT, $options)); // int(25)

Saída:

bool(false)
int(25)

Flags úteis incluem FILTER_NULL_ON_FAILURE (retorna null em vez de false), FILTER_FLAG_STRIP_LOW (remove caracteres abaixo de ASCII 32) e FILTER_FLAG_IPV6 / FILTER_FLAG_IPV4 para restringir FILTER_VALIDATE_IP.

filter_input() — filtrar dados de requisição diretamente

filter_input() lê um valor diretamente de uma superglobal (pelo nome) e o filtra em uma única etapa, de modo que você nunca toca no array bruto $_POST / $_GET:

filter_input(int $type, string $var_name, int $filter = FILTER_DEFAULT, array|int $options = 0): mixed

O $type é um de INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER ou INPUT_ENV:

<?php
// In a real form handler:
$email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);

if ($email === false) {
    echo "Please enter a valid email.";
} elseif ($email === null) {
    echo "The email field was not submitted.";
} else {
    echo "Got: $email";
}

Observe os três resultados possíveis: um valor (aprovado), false (presente mas inválido) ou null (o campo não foi enviado). Para filtrar um formulário inteiro de uma vez, consulte filter_var_array() e filter_input_array().

Constantes de filtro comuns

Descontinuado desde o PHP 8.1: FILTER_SANITIZE_STRING (e seu alias FILTER_SANITIZE_STRIPPED). Para escapar saída use htmlspecialchars(); para limpar entrada prefira um filtro de validação específico mais escaping apropriado ao contexto no ponto de uso.

Quando devo usar isso?

• Verificar um formulário de cadastro ou contato antes de salvar — combine com PHP Form Validation e validating URL & e-mail fields.
• Confirmar que um id de query string é um inteiro positivo antes de consultar o banco de dados.
• Ler e confiar em valores de cookies ou $_SERVER.

O filtro complementa, mas não substitui, outras defesas: use prepared statements (PHP MySQLi prepared statements) contra injeção SQL e htmlspecialchars() ao exibir dados do usuário em HTML. Para regras baseadas em padrões que a extensão filter não consegue expressar, recorra a expressões regulares.

Prática