A Função array_filter() do PHP: Guia Completo

array_filter() é uma função PHP nativa que retorna um novo array contendo apenas os elementos do array original que passam em um teste definido por você. Você fornece um callback — uma função que retorna true para manter um elemento e false para descartá-lo — e array_filter() o executa para cada elemento.

Esta página explica como a função funciona, seus três modos de operação (filtragem por valor, por chave ou por ambos), o comportamento que surpreende a maioria dos iniciantes (preservação de chaves) e o atalho para remover valores "vazios".

Como o array_filter() Funciona

array_filter() percorre o array elemento por elemento e chama seu callback em cada um deles:

• Se o callback retornar um valor truthy, o elemento é mantido.
• Se retornar um valor falsy, o elemento é descartado.

O array original nunca é modificado — array_filter() constrói e retorna um novo array. Por padrão, o callback recebe o valor do elemento (não a sua chave).

Sintaxe

array_filter(array $array, ?callable $callback = null, int $mode = 0): array

• $array — o array a ser filtrado.
• $callback — a função de teste. Opcional: se omitida, todo elemento igual a um valor falsy (false, 0, 0.0, "", "0", null, []) é removido.
• $mode — controla o que o callback recebe. Pode ser 0 (padrão, o valor), ARRAY_FILTER_USE_KEY ou ARRAY_FILTER_USE_BOTH. Veja Filtragem por chave.

Filtrando com um Callback Personalizado

O uso mais comum é filtrar por uma condição personalizada. Aqui mantemos apenas os números pares:

Saída:

Array ( [1] => 2 [3] => 4 [5] => 6 )

Observe as chaves: os elementos mantidos preservam suas chaves originais (1, 3, 5), eles não são renumerados. Essa é a maior surpresa do array_filter(). Veja Reindexando o resultado abaixo para a solução.

No PHP moderno, você pode escrever o callback como uma arrow function concisa:

$evenNumbers = array_filter($numbers, fn ($number) => $number % 2 === 0);

Usando uma Função Nativa como Callback

O callback pode ser qualquer callable, incluindo uma função nativa passada pelo nome. Aqui, is_numeric mantém apenas os valores numéricos:

Saída:

Array ( [0] => 1 [1] => 2 [3] => 4 [4] => 5 )

A string '2' é mantida porque is_numeric('2') é true, enquanto 'three' é descartada.

Removendo Valores Vazios (Sem Callback)

Chame array_filter() com apenas o array para remover todos os elementos falsy — uma maneira rápida de limpar uma lista de entradas opcionais:

<?php

$values = [0, 1, 2, '', '0', 'hello', null, false, []];

print_r(array_filter($values));

?>

Saída:

Array ( [1] => 1 [2] => 2 [5] => hello )

Atenção: isso remove 0, '0' e '' porque são falsy. Se um 0 ou '0' literal for significativo nos seus dados, passe um callback explícito, por exemplo fn ($v) => $v !== null.

Filtrando por Chave ou por Ambos

Por padrão, o callback só vê o valor. Passe o argumento $mode para alterar esse comportamento:

ARRAY_FILTER_USE_KEY passa a chave ao callback em vez do valor:

<?php

$data = ['a' => 1, 'b' => 2, 'ab' => 3];

// Keep only single-letter keys
$result = array_filter($data, fn ($key) => strlen($key) === 1, ARRAY_FILTER_USE_KEY);

print_r($result);

?>

Saída:

Array ( [a] => 1 [b] => 2 )

ARRAY_FILTER_USE_BOTH passa tanto o valor quanto a chave (valor primeiro):

<?php

$data = ['a' => 1, 'b' => 2, 'c' => 3];

$result = array_filter($data, fn ($value, $key) => $value > 1 && $key !== 'c', ARRAY_FILTER_USE_BOTH);

print_r($result);

?>

Saída:

Array ( [b] => 2 )

Reindexando o Resultado

Como array_filter() preserva as chaves, um array indexado pode ficar com lacunas ([1], [3], [5]). Quando você precisa de uma lista limpa com base zero — por exemplo, antes de codificá-la como um array JSON — envolva o resultado em array_values():

<?php

$numbers = [1, 2, 3, 4, 5, 6];

$even = array_values(array_filter($numbers, fn ($n) => $n % 2 === 0));

print_r($even);

?>

Saída:

Array ( [0] => 2 [1] => 4 [2] => 6 )

Quando Usar array_filter()

• Use array_filter() quando quiser um subconjunto de um array (descartar os elementos indesejados).
• Use array_map() quando quiser transformar cada elemento mantendo a mesma quantidade.
• Use array_reduce() quando quiser reduzir um array a um único valor.

filter, map e reduce se combinam bem — filtre primeiro, depois transforme os sobreviventes.

Conclusão

array_filter() é a forma idiomática de extrair um subconjunto de um array em PHP. Lembre-se dos dois comportamentos principais: o array original é preservado, e os elementos mantidos conservam suas chaves originais (use array_values() para reindexar). Com o callback opcional e os modos ARRAY_FILTER_USE_KEY / ARRAY_FILTER_USE_BOTH, ele lida com filtragem por valor, chave ou ambos. Para saber mais sobre arrays, consulte a visão geral de Arrays PHP.

Prática