Entendendo a Função preg_filter do PHP

A função preg_filter no PHP pesquisa uma string (ou array de strings) em busca de texto que corresponda a uma expressão regular e o substitui. Sua característica principal é que ela retorna apenas as entradas onde uma correspondência ocorreu — entradas sem correspondência são descartadas. Isso a torna ideal para tarefas em que você deseja pesquisar, substituir e filtrar em um único passo.

Se você já usou preg_replace, o preg_filter será familiar: a sintaxe é idêntica. A única diferença de comportamento — o que acontece com os sujeitos sem correspondência — é o que torna o preg_filter valioso, e é o foco desta página.

Neste artigo, abordaremos a sintaxe, os parâmetros, como o preg_filter difere do preg_replace, e os casos de uso mais comuns, cada um com um exemplo executável.

Sintaxe e Parâmetros

A sintaxe da função preg_filter é a seguinte:

Sintaxe do preg_filter em PHP

preg_filter(pattern, replacement, subject [, limit [, count]])

Os parâmetros são os seguintes:

• pattern: É um padrão de expressão regular que especifica o texto que você deseja pesquisar.
• replacement: É o texto que substituirá o texto correspondente no sujeito.
• subject: É a string na qual você deseja pesquisar e substituir o texto.
• limit (opcional): O número máximo de substituições por string de sujeito. O padrão é -1 (sem limite).
• count (opcional): Uma variável passada por referência que será preenchida com o número total de substituições realizadas.

Os argumentos pattern, replacement e subject podem ser um valor único ou um array, exatamente como no preg_replace. O valor de retorno é uma string quando subject é uma string, e um array quando subject é um array.

preg_filter vs. preg_replace

As duas funções recebem os mesmos argumentos e realizam o mesmo trabalho de busca e substituição. A diferença está no que retornam quando um sujeito não corresponde ao padrão:

• preg_replace retorna o sujeito inalterado.
• preg_filter retorna null para um sujeito string e omite a entrada completamente para um sujeito array.

<?php
$input = ["123", "abc", "456"];

// preg_replace keeps every element, matched or not.
print_r(preg_replace("/\d+/", "[num]", $input));
// Array ( [0] => [num] [1] => abc [2] => [num] )

// preg_filter drops the non-matching "abc".
print_r(preg_filter("/\d+/", "[num]", $input));
// Array ( [0] => [num] [2] => [num] )
?>

Observe que o preg_filter preserva as chaves originais (0 e 2) — ele não reindexa o array.

Casos de Uso

O preg_filter é mais útil quando você precisa pesquisar, substituir e filtrar ao mesmo tempo. Os casos de uso mais comuns incluem:

• Filtragem de arrays: Passe um array de strings e obtenha de volta apenas os elementos que corresponderam ao padrão.
• Remoção de tags HTML: Remova tags de strings ou arrays de strings.
• Extração e reformatação: Substitua o texto correspondente enquanto descarta entradas que não contêm nada de interesse.

Exemplo: Removendo tags HTML

Neste exemplo, usaremos o preg_filter para remover tags HTML de uma string:

Exemplo de preg_filter em PHP

Neste exemplo, estamos usando o padrão de expressão regular /<[^>]+>/ para corresponder a todas as tags HTML na string $html. O parâmetro replacement é definido como uma string vazia, portanto o texto correspondente é removido. O texto resultante é então armazenado na variável $text e exibido na tela.

Exemplo: Filtrando elementos de um array

O preg_filter se destaca ao trabalhar com arrays, pois remove os elementos sem correspondência:

<?php
$items = ["apple", "banana", "apricot", "cherry"];
$filtered = preg_filter("/^a/", "A", $items);
print_r($filtered);
// Outputs:
// Array
// (
//     [0] => Apple
//     [2] => Apricot
// )
?>

Neste exemplo, o preg_filter substitui o "a" inicial por "A", mas remove automaticamente "banana" e "cherry" porque não correspondem ao padrão. Os elementos mantidos preservam suas chaves originais (0 e 2).

Contando substituições com o parâmetro count

O quinto parâmetro opcional é preenchido por referência com o número de substituições realizadas, o que é útil para relatórios ou para ramificar com base em se algo correspondeu:

<?php
$subject = "Order #42 and order #7";
$result = preg_filter("/#(\d+)/", "[$1]", $subject, -1, $count);
echo $result . "\n";   // Order [42] and order [7]
echo $count . "\n";    // 2
?>

Aqui, $1 na substituição é uma referência retroativa ao primeiro grupo de captura. Duas correspondências foram substituídas, portanto $count é 2.

Conclusão

O preg_filter realiza uma busca e substituição com expressão regular assim como o preg_replace, mas descarta os sujeitos que não correspondem — retornando null para strings e removendo elementos sem correspondência de arrays. Isso o torna a escolha certa quando filtragem e substituição pertencem juntas em um único passo.

Para aprofundar-se no conjunto de ferramentas de regex do PHP, veja preg_match para testar uma única correspondência, preg_match_all para encontrar todas as correspondências, preg_split para dividir strings e preg_replace_callback quando a substituição precisar ser calculada em código.

Prática