PHP filter_var(): validar e-mail, inteiro, URL e mais

filter_var($value, FILTER_VALIDATE_EMAIL) retorna o valor quando ele é um endereço de e-mail válido e false quando não é. Troque o filtro para verificar outros formatos: FILTER_VALIDATE_INT, FILTER_VALIDATE_FLOAT, FILTER_VALIDATE_URL, FILTER_VALIDATE_BOOL, FILTER_VALIDATE_IP. Sempre compare o resultado com === false.

<?php
$emails = ['ada@example.com', 'ada.lovelace+news@example.co.uk', 'ada@', 'ada@example', 'ada..x@example.com', ' ada@example.com'];

foreach ($emails as $email) {
    $ok = filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
    printf("%-34s %s\n", "'$email'", $ok ? 'valid' : 'invalid');
}

Dois resultados surpreendem. ada@example é rejeitado porque o domínio não tem ponto, e ' ada@example.com' é rejeitado por causa do espaço inicial, então aplique trim() na entrada antes de validá-la.

Validar um e-mail vindo de um formulário

A mesma verificação atrás de um formulário. Rode, digite um endereço e clique em Check; o bloco roda de novo com a sua entrada em $_POST.

<?php
$email = trim((string) ($_POST['email'] ?? ''));
$result = '';

if ($email !== '') {
    $result = filter_var($email, FILTER_VALIDATE_EMAIL) !== false
        ? '<b style="color:#2e7d32">valid</b>'
        : '<b style="color:#c62828">invalid</b>';
}
?>
<form method="post">
  <input name="email" size="30" value="<?= htmlspecialchars($email) ?>" placeholder="you@example.com">
  <button>Check</button>
</form>
<?php if ($result): ?><p><?= htmlspecialchars($email) ?> is <?= $result ?></p><?php endif; ?>

O FILTER_VALIDATE_EMAIL verifica só o formato. nobody@example.com passa, e passaria também um endereço com erro de digitação no domínio. Caracteres fora do ASCII são rejeitados: adä@example.com só passa com FILTER_FLAG_EMAIL_UNICODE, que os permite antes do @, e um domínio como exämple.com falha mesmo com a flag, a menos que você o converta antes para a forma xn--. O único jeito de saber se um endereço funciona é enviar um link de confirmação para ele.

Validar um inteiro, com min_range e max_range

O FILTER_VALIDATE_INT transforma uma string válida num int e rejeita todo o resto. O array de opções adiciona um intervalo e um padrão:

<?php
$inputs = ['42', '-7', ' 42 ', '+42', '4.2', '042', '42abc', '', '0'];

foreach ($inputs as $in) {
    echo str_pad("'$in'", 8), ' => ';
    var_dump(filter_var($in, FILTER_VALIDATE_INT));
}

$age = filter_var('150', FILTER_VALIDATE_INT, [
    'options' => ['min_range' => 0, 'max_range' => 120],
]);
var_dump($age);

$page = filter_var('abc', FILTER_VALIDATE_INT, ['options' => ['default' => 1]]);
var_dump($page);

Espaços em volta e um + inicial são aceitos, um zero à esquerda ('042') não, e o resultado para '42' é o inteiro 42, não a string. Fora do intervalo dá false; com a opção default você recebe o padrão em vez de false, o que é prático para coisas como ?page= (veja $_GET e$_POST). Adicione FILTER_FLAG_ALLOW_HEX ou FILTER_FLAG_ALLOW_OCTAL para aceitar 0x1A ou 0755.

A armadilha do 0 e do false

Um '0' válido retorna o inteiro 0, e 0 é falso. Um if simples o trata como falha:

<?php
$quantity = '0';

if (filter_var($quantity, FILTER_VALIDATE_INT)) {
    echo "if (...): valid\n";
} else {
    echo "if (...): rejected, wrongly\n";
}

if (filter_var($quantity, FILTER_VALIDATE_INT) !== false) {
    echo "!== false: valid\n";
}

// Or get null instead of false on failure, and check for null
$n = filter_var('abc', FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);
var_dump($n);

O mesmo vale para FILTER_VALIDATE_FLOAT ('0.0') e FILTER_VALIDATE_BOOL, em que false é uma resposta válida. É para isso que serve o FILTER_NULL_ON_FAILURE.

Booleanos, floats, URLs e endereços IP

<?php
// Booleans: "1", "true", "on", "yes" are true; "0", "false", "off", "no", "" are false
foreach (['yes', 'off', 'TRUE', 'maybe'] as $v) {
    echo str_pad($v, 6), ' => ', var_export(filter_var($v, FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE), true), "\n";
}

// Floats: the decimal separator is "." unless you say otherwise
var_dump(filter_var('3.14', FILTER_VALIDATE_FLOAT));
var_dump(filter_var('3,14', FILTER_VALIDATE_FLOAT));
var_dump(filter_var('3,14', FILTER_VALIDATE_FLOAT, ['options' => ['decimal' => ',']]));
var_dump(filter_var('1,000.5', FILTER_VALIDATE_FLOAT, FILTER_FLAG_ALLOW_THOUSAND));

// URLs need a scheme
var_dump(filter_var('https://coddy.tech/docs?x=1', FILTER_VALIDATE_URL));
var_dump(filter_var('coddy.tech', FILTER_VALIDATE_URL));

// IP addresses, optionally excluding private ranges
var_dump(filter_var('192.168.1.10', FILTER_VALIDATE_IP));
var_dump(filter_var('192.168.1.10', FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE));

FILTER_VALIDATE_BOOL é o nome do PHP 8; FILTER_VALIDATE_BOOLEAN é o mesmo filtro. Sem FILTER_NULL_ON_FAILURE, 'maybe' retornaria false, impossível de distinguir de 'off'.

Uma URL válida não é um link seguro

O FILTER_VALIDATE_URL verifica se a string tem formato de URL, com qualquer esquema. Isso inclui esquemas que você nunca quer num href:

<?php
function isSafeLink(string $url): bool
{
    if (filter_var($url, FILTER_VALIDATE_URL) === false) {
        return false;
    }
    $scheme = strtolower((string) parse_url($url, PHP_URL_SCHEME));
    return in_array($scheme, ['http', 'https'], true);
}

foreach (['https://example.com', 'javascript://comment%0Aalert(1)', 'ftp://files.example.com', 'example.com'] as $url) {
    printf("%-36s filter_var: %-5s  safe link: %s\n",
        $url,
        filter_var($url, FILTER_VALIDATE_URL) !== false ? 'yes' : 'no',
        isSafeLink($url) ? 'yes' : 'no');
}

javascript://comment%0Aalert(1) passa no FILTER_VALIDATE_URL, e um navegador o executa como JavaScript quando o link é clicado, porque o %0A encerra o //comment. Verifique o esquema com parse_url() antes de imprimir a URL de um usuário numa página. Você também pode exigir partes com FILTER_FLAG_PATH_REQUIRED e FILTER_FLAG_QUERY_REQUIRED.

Filtros de sanitização

Filtros de sanitização removem caracteres em vez de dizer sim ou não. Eles servem para normalizar a entrada, não para torná-la segura para impressão:

<?php
var_dump(filter_var('Order #12-345 (x2)', FILTER_SANITIZE_NUMBER_INT));
var_dump(filter_var('$1,299.99', FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION));
var_dump(filter_var('ada (at) example.com', FILTER_SANITIZE_EMAIL));
var_dump(filter_var('<b>Tom</b> & "Jerry"', FILTER_SANITIZE_FULL_SPECIAL_CHARS));

Olhe a primeira linha: Order #12-345 (x2) vira 12-3452, um número que nunca esteve na entrada, e a terceira linha é um endereço que ninguém digitou. Se você sanitizar, valide o resultado depois. Para tudo o que você imprime no HTML, o htmlspecialchars() na hora da saída é a ferramenta certa (FILTER_SANITIZE_FULL_SPECIAL_CHARS faz o mesmo escape). O FILTER_SANITIZE_STRING está depreciado desde o PHP 8.1; veja htmlspecialchars para o que usar no lugar.

Validar um formulário inteiro com filter_var_array

O filter_var_array() aplica um filtro por chave e retorna um array com todas as chaves que você pediu: o valor filtrado, false quando a validação falhou, ou null quando a chave não existia.

<?php
$input = ['age' => '31', 'email' => 'not-an-email', 'newsletter' => 'on', 'role' => 'admin'];

$clean = filter_var_array($input, [
    'age'        => ['filter' => FILTER_VALIDATE_INT, 'options' => ['min_range' => 13]],
    'email'      => FILTER_VALIDATE_EMAIL,
    'newsletter' => ['filter' => FILTER_VALIDATE_BOOL, 'flags' => FILTER_NULL_ON_FAILURE],
    'country'    => FILTER_DEFAULT,
]);

var_dump($clean);

role sumiu: chaves que você não listou são descartadas, o que impede um visitante de adicionar role=admin a um formulário e tê-lo salvo. country é null porque não foi enviado. Num servidor web, filter_input_array(INPUT_POST, $rules) faz o mesmo lendo direto da requisição.