filter_list()

Introdução

filter_list() é uma função PHP que retorna os nomes de todos os filtros suportados pela sua compilação do PHP. A extensão de filtros do PHP é o mecanismo por trás das funções de validação e sanitização como filter_var() e filter_input(). Cada filtro — para e-mails, inteiros, URLs, endereços IP e assim por diante — tem um nome curto e um ID numérico, e filter_list() permite descobrir quais estão realmente disponíveis em tempo de execução.

Esta página aborda a assinatura da função, o que ela retorna, como difere das constantes FILTER_* nomeadas e os cenários práticos em que listar os filtros é útil (por exemplo, construir diagnósticos ou verificar a disponibilidade de um recurso antes de depender de um filtro).

Sintaxe

filter_list(): array

Não recebe nenhum argumento e retorna um array indexado de strings — o nome curto de cada filtro suportado pela sua instalação do PHP. A ordem não é garantida e pode diferir entre versões do PHP, portanto, nunca dependa de uma posição específica.

Valor de retorno

Os valores do array são nomes de filtros (como "validate_email" ou "int"), e as chaves do array são simplesmente inteiros sequenciais (0, 1, 2…). As chaves não são IDs de filtros — um equívoco comum. Para obter o ID numérico real de um filtro, passe seu nome para filter_id():

<?php

$filters = filter_list();
echo $filters[0] . "\n";            // e.g. "int"
echo filter_id($filters[0]) . "\n"; // e.g. 257  (FILTER_VALIDATE_INT)

Esses nomes curtos são o equivalente em tempo de execução das constantes FILTER_* que você normalmente usa:

Listando todos os filtros disponíveis

O uso mais comum é enumerar todos os filtros, geralmente junto com seu ID numérico para uma referência rápida:

<?php

foreach (filter_list() as $name) {
    echo $name . " => " . filter_id($name) . "\n";
}

Saída (o conjunto exato depende da sua versão do PHP):

int => 257
boolean => 258
float => 259
validate_regexp => 272
validate_domain => 277
validate_url => 273
validate_email => 274
validate_ip => 275
validate_mac => 276
string => 513
stripped => 513
encoded => 514
special_chars => 515
full_special_chars => 522
unsafe_raw => 516
email => 517
url => 518
number_int => 519
number_float => 520
add_slashes => 523
callback => 1024

Observe que string e stripped compartilham o ID 513 — são dois nomes para o mesmo filtro.

Quando usar?

Raramente você chama filter_list() no código de validação do dia a dia — para isso, use filter_var() com uma constante FILTER_*. filter_list() é útil para:

• Diagnósticos e ferramentas. Exibir os filtros suportados em uma página de depuração ou em um dump de informações do ambiente.
• Detecção de recursos. Confirmar que um filtro existe antes de depender dele, especialmente para filtros dependentes de compilação ou específicos de versão.
• Construção de interfaces dinâmicas. Preencher um menu suspenso que permite a um administrador escolher qual filtro aplicar.

Verificando se um filtro específico existe

Como os valores são strings simples, você pode testar a presença de um filtro com in_array():

<?php

if (in_array("validate_email", filter_list(), true)) {
    echo "Email validation is available.\n";
} else {
    echo "Email filter is missing.\n";
}

Saída:

Email validation is available.

Armadilhas comuns

• As chaves são índices, não IDs. Use filter_id() para converter um nome no ID aceito por filter_var().
• Nomes versus constantes. filter_list() retorna nomes curtos ("int"), não os nomes das constantes (FILTER_VALIDATE_INT). Não compare os dois diretamente.
• A ordem é instável. Sempre busque pelo nome, nunca pela posição.

Funções relacionadas

• filter_id() — obtém o ID numérico de um nome de filtro.
• filter_var() — aplica um filtro a um único valor.
• filter_input() — filtra um valor de uma fonte externa (GET, POST, etc.).
• filter_var_array() — filtra vários valores de uma só vez.

Conclusão

filter_list() retorna os nomes de todos os filtros suportados pela sua compilação do PHP. É principalmente uma ferramenta de descoberta e diagnóstico: combine-a com filter_id() para inspecionar IDs, use in_array() para verificar disponibilidade e recorra a filter_var() quando precisar validar ou sanitizar dados de verdade.

Prática