PHP array_map: guia completo com exemplos práticos

O que é a função array_map?

A função array_map é uma ferramenta essencial em PHP, permitindo a transformação de arrays sem alterar a estrutura original dos dados. Sendo assim, os desenvolvedores a utilizam frequentemente para aplicar lógicas personalizadas em elementos de arrays de maneira eficiente.

Sintaxe e parâmetros básicos

O array_map aceita uma função de retorno de chamada como seu primeiro parâmetro, seguida por um ou mais arrays. Essa função pode ser uma função nomeada, uma função anônima ou uma função de seta, disponível nas versões mais recentes do PHP. Além disso, quando múltiplos arrays são fornecidos, a função de retorno de chamada recebe os elementos correspondentes de cada array até que o menor deles se esgote. Parâmetros opcionais permitem ajustes finos, mas a função sempre retorna um novo array, preservando as chaves apenas quando um único array é passado sem reindexação.

$result = array_map('callback', $array1, $array2);

Essa estrutura garante segurança de tipo e suporta tipos de dados mistos em matrizes.

Trabalhando com matrizes indexadas

Matrizes indexadas se beneficiam do array_map para tarefas como formatação de dados. Por outro lado, você pode aplicar funções de string diretamente ou através de retornos de chamada para processar índices numéricos sequencialmente. Por exemplo, duplicar valores em uma matriz de números inteiros resulta em uma coleção transformada, pronta para cálculos adicionais.

$numbers = [1, 2, 3, 4];
$doubled = array_map(fn($n) => $n * 2, $numbers);

O resultado é [2, 4, 6, 8]. Essa abordagem evita loops manuais, mantendo a legibilidade do código. Operações mais complexas, como arredondamento de pontos flutuantes ou corte de strings, seguem padrões semelhantes, proporcionando resultados consistentes em grandes conjuntos de dados.

Manipulação de matrizes associativas

Quando se trata de matrizes associativas, o array_map mantém suas chaves durante o mapeamento ao processar uma única entrada. Retornos de chamada personalizados podem acessar valores e chaves indiretamente, utilizando técnicas adicionais como array_keys combinadas com array_map. Como resultado, a transformação de dados do usuário, como converter nomes para letras maiúsculas enquanto preserva os identificadores, demonstra sua utilidade prática.

$users = ['id1' => 'john', 'id2' => 'jane'];
$formatted = array_map('ucfirst', $users);

As chaves permanecem intactas, garantindo cenários onde a integridade dos dados depende da indexação original.

Usando múltiplos arrays

Ao fornecer duas ou mais matrizes, você permite operações elemento a elemento entre conjuntos de dados. O retorno de chamada recebe parâmetros na ordem de aparecimento dos arrays. Por conseguinte, a fusão de preços com quantidades para calcular totais ilustra essa capacidade de forma eficaz.

$prices = [10, 20, 30];
$quantities = [2, 3, 1];
$totals = array_map(fn($p, $q) => $p * $q, $prices, $quantities);

O resultado é [20, 60, 30]. O menor comprimento do array governa a iteração, evitando erros de índice automaticamente.

Funções anônimas e funções de seta

Com a introdução do PHP 7.4, as funções de seta proporcionam uma sintaxe mais concisa para o array_map. Elas substituem fechamentos mais complexos ao capturar variáveis do escopo. Assim, as operações combinadas de filtragem e mapeamento tornam-se mais simples para tarefas como limpeza de matrizes de entrada.

$raw = [' apple ', 'banana '];
$clean = array_map(fn($item) => trim(strtolower($item)), $raw);

Embora as funções nomeadas ainda sejam viáveis para lógica reutilizável, as definições inline reduzem a sobrecarga em transformações únicas.

Exemplos práticos em processamento de dados

Aplicativos de comércio eletrônico utilizam array_map para normalizar listagens de produtos, convertendo moedas ou aplicando descontos uniformemente. Além disso, as respostas de APIs frequentemente exigem o mapeamento de matrizes decodificadas em JSON para objetos de modelo ou strings formatadas para exibição no frontend. Os conjuntos de resultados de bancos de dados também se beneficiam da conversão de carimbos de data/hora em datas legíveis, sem alterar as consultas de origem.

$products = [['price' => 100], ['price' => 200]];
$discounted = array_map(fn($p) => $p['price'] * 0.9, $products);

Esses padrões são escaláveis para processamento em lote, mantendo o uso de memória baixo através da avaliação lenta em operações encadeadas.

Desempenho e melhores práticas

Embora o array_map supere loops foreach em legibilidade, pode haver uma leve sobrecarga com retornos de chamada complexos em matrizes muito grandes. Portanto, sempre valide os tipos de retorno da função de retorno de chamada para evitar valores nulos inesperados. Além disso, combine com array_filter para fluxos de trabalho de mapeamento seletivo. Prefira funções de seta em bases de código modernas voltadas para PHP 7.4 ou superior.

Armadilhas comuns a serem evitadas

Passar strings não chamáveis pode gerar avisos, então verifique a existência da função previamente. Além disso, comprimentos de matrizes incompatíveis truncam silenciosamente os resultados, o que exige verificações de comprimento em aplicativos críticos. A reindexação ocorre automaticamente com múltiplos arrays, portanto, preserve as chaves manualmente utilizando array_combine quando necessário.

Alternativas e comparações

O array_walk modifica arrays no local, diferentemente do array_map, sendo mais adequado para cenários de mutação. Por outro lado, o array_reduce agrega valores em vez de gerar matrizes paralelas. A escolha entre array_map e outras funções depende se uma nova coleção ou efeitos colaterais são necessários. Comparar essas funções revela compensações na velocidade de execução para casos de uso específicos.

Perguntas Frequentes

O que é a função array_map em PHP?

A função array_map em PHP é utilizada para aplicar uma função a cada elemento de um ou mais arrays, retornando um novo array com os resultados.

Como funciona a sintaxe do array_map?

A sintaxe básica do array_map envolve passar uma função de retorno de chamada seguida por um ou mais arrays. A função é aplicada a cada elemento correspondente até que o menor array se esgote.

Quais são algumas melhores práticas ao usar array_map?

Entre as melhores práticas estão validar os tipos de retorno da função de retorno de chamada, utilizar funções de seta para clareza e combinar com array_filter para mapeamento seletivo.

Quais alternativas existem para array_map?

Alternativas ao array_map incluem array_walk, que modifica arrays no local, e array_reduce, que agrega valores em vez de criar novas matrizes.