preg_grep()

Introdução

preg_grep() filtra um array, mantendo apenas os elementos que correspondem (ou, opcionalmente, não correspondem) a uma expressão regular. É o membro orientado a arrays da família PCRE do PHP: em vez de testar uma única string como preg_match(), percorre cada elemento de um array e retorna um novo array com os elementos que passam no teste.

Esta página cobre a assinatura e os parâmetros da função, a diferença entre correspondência normal e invertida, como se comportam as chaves retornadas, usos práticos comuns e os cuidados a ter.

Sintaxe

preg_grep(string $pattern, array $array, int $flags = 0): array|false

A função aceita três parâmetros:

• $pattern — um padrão PCRE, escrito como string com delimitadores (ex.: /^g/, ~\d+~, #error#i).
• $array — o array de entrada a filtrar. Apenas seus valores são testados, nunca suas chaves.
• $flags (opcional) — passe a constante PREG_GREP_INVERT para retornar os elementos que não correspondem. O padrão é 0 (retornar os elementos correspondentes).

Retorna um novo array contendo os elementos correspondentes, preservando as chaves originais. Se o padrão for inválido, retorna false e emite um aviso.

Exemplo básico

preg_grep() percorre o array e mantém cada valor que corresponde ao padrão. Aqui mantemos apenas as cores que começam com a letra g:

Saída:

Array
(
    [2] => green
)

Observe a chave: green estava no índice 2 no array de entrada, e preg_grep() mantém essa chave no resultado. O array retornado, portanto, não é reindexado — se precisar de chaves sequenciais, envolva a chamada em array_values().

Filtrando com PREG_GREP_INVERT

Passe PREG_GREP_INVERT como terceiro argumento para inverter a lógica: você recebe de volta os elementos que não passam no padrão. Isso é útil para tarefas do tipo "remover as entradas inválidas". Aqui descartamos todas as strings que contêm um dígito:

<?php

$entries = ["apple1", "banana", "cherry7", "date", "fig2"];

$result = preg_grep("/[0-9]/", $entries, PREG_GREP_INVERT);

print_r($result);

Saída:

Array
(
    [1] => banana
    [3] => date
)

Apenas banana e date sobrevivem porque não contêm dígitos — e, novamente, suas chaves originais (1 e 3) são preservadas.

Casos de uso práticos

Filtrando linhas de log por nível

Uma tarefa comum é extrair apenas as linhas de erro de uma lista de entradas de log. Um padrão ancorado sensível a maiúsculas mantém a precisão:

<?php

$logs = [
    "INFO ok",
    "ERROR disk full",
    "WARN low mem",
    "ERROR timeout",
];

$errors = preg_grep("/^ERROR/", $logs);

print_r($errors);

Saída:

Array
(
    [1] => ERROR disk full
    [3] => ERROR timeout
)

Mantendo apenas strings totalmente numéricas

Ao validar entradas mistas, preg_grep() permite manter apenas os valores que correspondem a um formato estrito em uma única linha. As âncoras ^\d+$ garantem que a string inteira seja composta de dígitos:

<?php

$mixed = ["12", "ab", "3x", "99"];

$nums = preg_grep("/^\d+$/", $mixed);

print_r($nums);

Saída:

Array
(
    [0] => 12
    [3] => 99
)

Cuidados e dicas

• As chaves são preservadas, não redefinidas. Como mostrado acima, lacunas nas chaves do resultado são normais. Use array_values() se precisar de 0, 1, 2, ….
• Apenas os valores são testados. preg_grep() ignora completamente as chaves do array — não existe uma variante baseada em chaves.
• Padrões inválidos retornam false, não um array vazio. Sempre valide o tipo do resultado se o padrão vier de entrada do usuário: if ($result === false) { /* bad pattern */ }.
• Não modifica o array de entrada. Como a maioria dos auxiliares de array do PHP, retorna um novo array e deixa $array intacto.
• Valores não-string são convertidos. Números e outros escalares são convertidos para string antes da correspondência, então preg_grep("/^1/", [10, 20]) corresponde a 10.

Funções relacionadas

• preg_match() — testa uma única string contra um padrão.
• preg_match_all() — encontra todas as correspondências dentro de uma string.
• preg_replace() — pesquisa e substitui usando um padrão.
• preg_split() — divide uma string em um array por um padrão.
• preg_filter() — como preg_replace(), mas retorna apenas os sujeitos correspondidos.

Conclusão

preg_grep() é a forma mais limpa de filtrar um array com uma expressão regular em PHP. Use-a sozinha para manter os elementos correspondentes, adicione PREG_GREP_INVERT para removê-los e lembre-se de que ela preserva as chaves originais. Para correspondência em uma única string, use preg_match(); para substituição, use preg_replace().

Prática