Como funciona array_map() no PHP (e quando não usar)

Você tem um array e precisa de outro igual, com cada item transformado — nomes em maiúsculas, preços com desconto, objetos virando strings. Dá para resolver com foreach, mas o PHP tem uma função feita exatamente para isso: o array_map(). Aqui você vai ver como ele funciona, quando o foreach continua sendo a escolha certa e as três pegadinhas que mais derrubam quem está começando.

O que o array_map() faz

Ele recebe uma função (o callback) e um array, e devolve um array novo, do mesmo tamanho, com o callback aplicado a cada item. O array original não muda.

$precos = [100, 250, 400];

$comDesconto = array_map(fn ($preco) => $preco * 0.9, $precos);
// [90, 225, 360] — e $precos continua [100, 250, 400]

Desde o PHP 7.4, as arrow functions (fn) deixam a chamada curta assim. E a partir do PHP 8.1 dá para passar qualquer função existente com a sintaxe de first-class callable:

$linhas = ['  php  ', '  arrays  '];

$limpas = array_map(trim(...), $linhas);   // ['php', 'arrays']

array_map ou foreach? A diferença é a intenção

Os dois chegam ao mesmo resultado; o que muda é o que o código comunica. array_map declara "estou transformando item a item, sem efeitos colaterais". Já o foreach é genérico: transforma, mas também salva no banco, imprime, acumula — o leitor precisa ler o corpo inteiro para saber.

$nomes = [];
foreach ($usuarios as $usuario) {
    $nomes[] = mb_strtoupper($usuario['nome']);
}

$nomes = array_map(
    fn ($usuario) => mb_strtoupper($usuario['nome']),
    $usuarios
);

A versão da direita não é "mais rápida" — é mais honesta: sem variável acumuladora declarada fora do laço, sem espaço para alguém enfiar um efeito colateral no meio da transformação.

As três pegadinhas

1. null no lugar do callback muda tudo

Com null e vários arrays, o array_map não transforma nada: ele agrupa os itens posição a posição (a operação zip):

$frutas = ['maçã', 'uva'];
$cores  = ['vermelha', 'roxa'];

array_map(null, $frutas, $cores);
// [['maçã', 'vermelha'], ['uva', 'roxa']]

Ótimo quando é isso que você quer — uma surpresa e tanto quando o null chegou ali por acidente (uma variável de callback que ninguém inicializou, por exemplo).

2. O callback nunca vê as chaves

O callback recebe só o valor de cada item. Com um array associativo e um único array de entrada, as chaves são preservadas no resultado — mas dentro do callback você não tem acesso a elas:

$idades = ['ana' => 28, 'bia' => 34];

array_map(fn ($idade) => $idade + 1, $idades);
// ['ana' => 29, 'bia' => 35] — chaves intactas, mas o callback só viu 28 e 34

Quando a transformação depende da chave, use foreach — ou passe as chaves como um segundo array:

$frases = array_map(
    fn ($nome, $idade) => "$nome tem $idade anos",
    array_keys($idades),
    $idades
);
// ['ana tem 28 anos', 'bia tem 34 anos']

3. Vários arrays: reindexação e tamanhos diferentes

Ao passar mais de um array, o resultado é sempre reindexado do zero (0, 1, 2…) — as chaves originais se perdem. E se os arrays têm tamanhos diferentes, os menores são completados com null até o tamanho do maior:

$a = [1, 2, 3];
$b = [10, 20];

array_map(fn ($x, $y) => $x + $y, $a, $b);
// [11, 22, 3] — o segundo array ganhou um null no fim (3 + null = 3)

Qual ferramenta para qual tarefa

Continue de onde este artigo parou