filter_input()

Introdução

filter_input() é uma função nativa do PHP que lê uma única variável externa — de $_GET, $_POST, cookies, do ambiente do servidor ou de getenv() — e a passa por um filtro em uma única etapa. Um filtro pode sanitizar o valor (remover ou escapar caracteres indesejados) ou validar o valor (verificar se ele corresponde a um formato esperado e rejeitá-lo caso contrário).

O principal motivo para usar filter_input() em vez de acessar $_GET['x'] diretamente é a segurança por design: você nunca recebe uma superglobal bruta nas mãos, a função reporta claramente quando uma variável está ausente, e o filtro é aplicado no exato momento em que o valor é lido. Esta página cobre a sintaxe, a diferença entre sanitizar e validar, como interpretar os três possíveis valores de retorno e um exemplo completo de tratamento de formulário.

Precisa filtrar um valor que já está em uma variável (não proveniente de uma superglobal)? Use filter_var(). Para filtrar vários campos de uma vez, veja filter_input_array().

Sintaxe

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

O que ela retorna

filter_input() possui três possíveis valores de retorno, e distingui-los é justamente o ponto de usá-la:

• o valor filtrado em caso de sucesso;
• false se a filtragem (validação) falhar;
• null se a variável não estiver definida na fonte de entrada solicitada.

Como false e null têm significados diferentes, use === em vez de uma verificação de veracidade simples.

Sanitizar vs. validar

Este é o ponto de confusão mais comum, então faça a escolha de forma deliberada:

• Sanitizar (FILTER_SANITIZE_*) — limpa o valor e retorna a string limpa. Quase nunca "falha"; apenas remove ou escapa caracteres.
• Validar (FILTER_VALIDATE_*) — verifica o valor e o retorna inalterado em caso de sucesso, ou false em caso de falha. Use quando o campo tem um formato rígido (e-mail, inteiro, URL, boolean).

FILTER_SANITIZE_STRING foi removido no PHP 8.0. Use FILTER_SANITIZE_FULL_SPECIAL_CHARS (ou htmlspecialchars() no momento da saída) como substituto.

Sanitizando entrada

O exemplo abaixo lê um campo name de uma requisição POST e escapa quaisquer caracteres especiais HTML para que o valor seja seguro para armazenar e exibir posteriormente.

<?php

$name = filter_input(INPUT_POST, 'name', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

if ($name === null) {
    $name = '';          // field was not submitted at all
}

echo $name;

FILTER_SANITIZE_FULL_SPECIAL_CHARS codifica em HTML cada caractere especial (similar a htmlspecialchars() com ENT_QUOTES), então <b>Joe</b> se torna <b>Joe</b>.

Validando entrada

Para campos com formato fixo, valide em vez de sanitizar. Aqui, FILTER_VALIDATE_EMAIL retorna o endereço em caso de sucesso ou false em caso de falha:

<?php

$email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);

if ($email === null) {
    echo "No email submitted.";
} elseif ($email === false) {
    echo "Invalid email address.";
} else {
    echo "Valid email: $email";
}

Validando números com opções

O quarto parâmetro permite restringir um valor. Este exemplo aceita um número de página inteiro apenas quando ele está entre 1 e 100, e utiliza 1 como fallback caso contrário:

<?php

$page = filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT, [
    'options' => [
        'min_range' => 1,
        'max_range' => 100,
        'default'   => 1,   // returned when validation fails
    ],
]);

echo "Page: $page";

Um exemplo completo de formulário

Em uma requisição real, você lê cada campo diretamente da fonte de entrada:

<?php

$name  = filter_input(INPUT_POST, 'name',  FILTER_SANITIZE_FULL_SPECIAL_CHARS);
$email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);
$age   = filter_input(INPUT_POST, 'age',   FILTER_VALIDATE_INT, [
    'options' => ['min_range' => 0, 'max_range' => 120],
]);

$errors = [];
if ($email === false) {
    $errors[] = 'Invalid email.';
}
if ($age === false) {
    $errors[] = 'Age must be a whole number between 0 and 120.';
}

if ($errors) {
    echo implode("\n", $errors);
} else {
    echo "Name:  $name\nEmail: $email\nAge:   $age\n";
}

Para um envio válido (name=<b>Jane</b>, [email protected], age=34) isto imprime:

Name:  <b>Jane</b>
Email: [email protected]
Age:   34

Nota: filter_input() lê as variáveis que o PHP capturou da requisição HTTP real, não valores que você atribuiu posteriormente a $_GET/$_POST no código. Isso a torna resistente a adulterações, mas também significa que a função retorna null para todos os campos quando um script é executado a partir da linha de comando sem uma requisição por trás — teste filtros de entrada com filter_var() em uma string de exemplo.

Quando usá-la

Use filter_input() sempre que um valor entrar na sua aplicação vindo do mundo externo:

• Query strings e formulários — leia campos INPUT_GET / INPUT_POST com o validador correto em vez de confiar nas superglobais brutas.
• Paginação, IDs, preços — FILTER_VALIDATE_INT / FILTER_VALIDATE_FLOAT com um guarda de intervalo rejeita entradas fora dos limites ou não numéricas antes que cheguem a uma consulta.
• Formulários de contato — FILTER_VALIDATE_EMAIL e FILTER_VALIDATE_URL impõem o formato na fronteira. Veja o exemplo completo em PHP Form Validation.

Filtrar na fronteira de entrada mantém a lógica de validação em um único lugar e a separa da lógica de negócio, o que torna o código mais fácil de ler, testar e auditar. Para a lista completa de filtros disponíveis, veja PHP Filters.

Conclusão

filter_input() lê uma variável externa e a filtra em uma única etapa bem definida. Use um filtro FILTER_VALIDATE_* quando um campo tem um formato rígido e um filtro FILTER_SANITIZE_* quando só precisa limpar um valor; e sempre verifique o retorno com === para distinguir uma variável ausente (null) de uma que falhou (false).

Prática