PHP array_map(): aplicar uma função a cada elemento

array_map($callback, $array) chama $callback em cada elemento de $array e retorna um novo array com os resultados. O callback vem primeiro, o array depois, e o array original continua inalterado.

<?php
$prices = [10, 25, 40];

$withTax = array_map(fn($p) => $p * 1.2, $prices);

print_r($withTax);
print_r($prices); // unchanged

fn($p) => $p * 1.2 é uma arrow function: uma função de uma expressão que retorna o resultado. Qualquer callable funciona no lugar dela.

Usar uma função nativa como callback

Passe o nome de uma função nativa como string. É o jeito mais curto de limpar um array inteiro: aplicar trim em cada valor, converter strings em inteiros ou mudar maiúsculas e minúsculas.

<?php
$raw = ["  apple ", "Banana  ", " cherry"];
print_r(array_map('trim', $raw));

$ids = ["4", "15", "42"];
var_dump(array_map('intval', $ids));

$names = ["ada", "grace", "linus"];
print_r(array_map('ucfirst', $names));

array_map('intval', ...) é o jeito comum de transformar as strings de um formulário ou do explode() em inteiros de verdade. Você também pode escrever intval(...), a sintaxe de callable de primeira classe do PHP 8.1, que o seu editor consegue completar e verificar.

Usar uma closure com variáveis de fora

Uma arrow function enxerga automaticamente as variáveis em volta dela. Uma function clássica precisa de use para trazê-las. As duas são explicadas na página sobre funções anônimas.

<?php
$rate = 0.15;
$amounts = [100, 250, 80];

// Arrow function: $rate is captured automatically
$tips = array_map(fn($a) => round($a * $rate, 2), $amounts);
print_r($tips);

// Classic closure: $rate must be listed in use()
$tips2 = array_map(function ($a) use ($rate) {
    return round($a * $rate, 2);
}, $amounts);
print_r($tips2);

array_map com chaves

Com um único array, o array_map mantém as chaves, incluindo chaves string. Mas o callback só recebe o valor. Para obter a chave também, passe array_keys($array) como segundo array: o callback é então chamado com um elemento de cada array.

<?php
$stock = ["apples" => 12, "pears" => 0, "plums" => 7];

// Keys are kept
print_r(array_map(fn($n) => $n * 2, $stock));

// Key and value in the callback
$lines = array_map(
    fn($name, $count) => "$name: $count",
    array_keys($stock),
    $stock
);
print_r($lines);

// Same, with the original keys put back
print_r(array_combine(array_keys($stock), $lines));

Repare no segundo resultado: assim que você passa mais de um array, as chaves são substituídas por 0, 1, 2. É por isso que a última linha usa array_combine() para reconstruí-las.

Mapear vários arrays de uma vez

Cada array extra vira um argumento extra do callback, emparelhado pela posição. Se os arrays tiverem tamanhos diferentes, os mais curtos são completados com null.

<?php
$first = ["Ada", "Grace", "Linus"];
$last  = ["Lovelace", "Hopper", "Torvalds"];

print_r(array_map(fn($f, $l) => "$f $l", $first, $last));

// Different lengths: missing values arrive as null
$a = [1, 2, 3];
$b = [10, 20];
print_r(array_map(fn($x, $y) => $x + ($y ?? 0), $a, $b));

Passar null como callback pula a função e junta os arrays em pares:

<?php
$names = ["Ada", "Grace"];
$years = [1815, 1906];

print_r(array_map(null, $names, $years));

array_map, array_walk ou foreach

O array_map monta um novo array. O array_walk altera o array que você passa, por referência, e entrega a chave como segundo argumento do callback. Um foreach faz qualquer um dos dois e também pode pular elementos ou parar cedo com break.

<?php
$tags = [" php ", " arrays", "map "];

// New array, input untouched
$clean = array_map('trim', $tags);

// Change in place: note the & before $value
array_walk($tags, function (&$value, $key) {
    $value = "#$key " . trim($value);
});

print_r($clean);
print_r($tags);

Use array_map quando cada elemento vira exatamente um novo elemento. Se você também precisa descartar alguns elementos, combine com o array_filter, ou escreva um foreach.

Erro comum: a ordem dos argumentos

O array_map recebe o callback primeiro e o array depois. O vizinho dele, array_filter, recebe na ordem inversa, o que é fácil de confundir:

array_map($callback, $array);     // callback first
array_filter($array, $callback);  // array first

Trocar os dois faz o PHP 8 lançar um TypeError, porque um array simples não é um callback válido:

<?php
// This throws a TypeError on purpose: the arguments are swapped
$numbers = [1, 2, 3];
$doubled = array_map($numbers, fn($n) => $n * 2);

O PHP para com:

PHP Fatal error:  Uncaught TypeError: array_map(): Argument #1 ($callback) must be a valid callback or null, array callback must have exactly two members in /home/index.php:4

Troque os dois argumentos de volta e o bloco roda.