filter_var()

Introdução

filter_var() é a ferramenta integrada do PHP para validar e sanitizar um único valor. Validar significa verificar se um valor corresponde ao formato esperado (um e-mail real, um inteiro dentro de um intervalo, uma URL válida) e retornar o valor caso corresponda, ou false caso não corresponda. Sanitizar significa limpar um valor removendo ou escapando caracteres que não pertencem a ele.

Nunca confie em dados que vêm de fora do seu script — campos de formulário, query strings, cookies, payloads de API. Processá-los com filter_var() antes de armazenar, exibir ou agir sobre eles é uma das maneiras mais simples de manter sua aplicação segura e previsível. Esta página aborda a sintaxe, os dois modos (validar vs. sanitizar), os filtros e flags mais comuns, e as armadilhas que costumam pegar as pessoas de surpresa.

Sintaxe

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

Valor de retorno: o valor filtrado (e possivelmente convertido) em caso de sucesso, ou false em caso de falha. Observe que um filtro de validação retorna o próprio valor — portanto, sempre compare com === quando o valor válido puder ser falsy (como 0 ou uma string vazia).

Validando dados

A validação responde a uma pergunta de sim/não: esse valor é aceitável? O filtro retorna o valor em caso de sucesso e false em caso de falha.

Validar um endereço de e-mail

Os filtros de validação mais úteis são:

A armadilha do === false

Como um filtro de validação retorna o valor, um resultado de 0 ou "0" é válido, mas falsy. Sempre use uma comparação estrita:

Sanitizando dados

A sanitização não rejeita um valor — ela o limpa e retorna a string limpa.

Sanitizar um endereço de e-mail

Filtros de sanitização comuns:

Nota: FILTER_SANITIZE_STRING foi descontinuado no PHP 8.1. Para limpar strings na saída HTML, prefira htmlspecialchars() no momento da exibição.

Usando opções e flags

O terceiro argumento ajusta um filtro. Passe-o como um array com 'options' (e opcionalmente 'flags'):

Flags também podem ser passadas diretamente como terceiro argumento quando você não precisa da forma de array:

Validar vs. sanitizar — quando usar cada um

• Validar quando você precisa de uma decisão de sim/não: rejeitar a requisição, mostrar um erro, tentar novamente. Use filtros de validação para e-mails, números, URLs e IPs em formulários e APIs.
• Sanitizar quando você precisa aceitar a entrada, mas quer que ela seja limpa de caracteres perigosos ou indevidos antes do uso.
• Os dois são complementares — um padrão comum é validar na entrada e escapar (ex.: com htmlspecialchars()) na saída, em vez de depender apenas de filtros de sanitização.

Armadilhas comuns

• Um filtro de validação retorna o valor, não true. Compare com === false para detectar falha.
• filter_var() funciona em um único valor escalar. Para filtrar muitos valores de uma vez, use filter_var_array() ou, para dados de requisição, filter_input_array().
• FILTER_VALIDATE_BOOLEAN retorna null (não false) para valores não reconhecidos somente quando você passa FILTER_NULL_ON_FAILURE; caso contrário, retorna false.
• Não dependa de filtros de sanitização para escapar saídas críticas de segurança — escape no momento da renderização.

Tópicos relacionados

• filter_var_array() — filtra muitas variáveis em uma única chamada.
• filter_input_array() — filtra dados de requisição ($_GET, $_POST).
• Validação de Formulários PHP — aplicando esses filtros em formulários reais.
• Validar URL e E-mail em PHP
• htmlspecialchars() — escapando para saída HTML segura.
• trim() — remove espaços em branco antes da filtragem.

Conclusão

filter_var() é uma maneira compacta e confiável de validar e sanitizar valores individuais em PHP. Use os filtros de validação para aceitar ou rejeitar entradas, os filtros de sanitização para limpá-las, e lembre-se de comparar os resultados de validação com === false. Combinado com filter_var_array() para dados em massa e htmlspecialchars() para saída, ele forma a base do tratamento seguro de entradas.

Prática