A Função array_walk() do PHP: Como Usá-la para Manipulação Eficiente de Arrays

array_walk() é uma função PHP integrada que aplica um callback a cada elemento de um array, no lugar. Ao contrário de array_map(), que constrói e retorna um novo array, array_walk() percorre o array existente e permite modificar cada elemento diretamente por referência. Esta página aborda sua sintaxe, quando usá-la em vez de um simples loop foreach ou array_map(), as armadilhas comuns relacionadas à modificação de valores e como percorrer arrays aninhados com array_walk_recursive().

Sintaxe

array_walk(array &$array, callable $callback, mixed $arg = null): true

array_walk() sempre retorna true (retorna false apenas em caso de erro de tipo). Ela não retorna o array modificado — o array passado é alterado diretamente.

Por que passar $value por referência? Sem o &, o callback recebe uma cópia de cada elemento, portanto qualquer alteração é descartada. Adicione & (como em function (&$value)) e suas edições são escritas de volta no array original. Veja funções PHP e callable para mais sobre callbacks.

Exemplos de uso de array_walk()

Exemplo 1: Modificando Arrays

Um dos usos principais de array_walk() é modificar arrays. Com sua capacidade de aplicar uma função definida pelo usuário a cada elemento de um array, é uma forma simples de transformar um array para atender às suas necessidades específicas. Veja um exemplo de como usar array_walk() para alterar o caso de todos os elementos de um array.

Exemplo PHP 1: Modificando Arrays

Saída:

Array
(
    [0] => APPLE
    [1] => BANANA
    [2] => CHERRY
)

Neste exemplo, primeiro definimos um array com três elementos. Em seguida, definimos uma função chamada change_case() que usa a função integrada do PHP strtoupper() para converter cada elemento para maiúsculas. Depois, usamos a função array_walk() para aplicar a função change_case() a cada elemento do array. Por fim, usamos a função print_r() para exibir o array modificado.

Exemplo 2: Realizando Cálculos

Outro uso poderoso de array_walk() é realizar cálculos em arrays. Com sua capacidade de aplicar uma função definida pelo usuário a cada elemento de um array, você pode usar array_walk() para executar uma ampla gama de cálculos. Veja um exemplo de como usar array_walk() para calcular a soma de todos os elementos de um array.

Exemplo 2: Realizando Cálculos

Saída:

The total sum is: 15

Neste exemplo, primeiro definimos um array com cinco elementos. Em seguida, definimos uma função anônima que adiciona cada elemento a um total acumulado. Usamos a função array_walk() para aplicar a função a cada elemento do array. Por fim, exibimos a soma total usando o comando echo.

Exemplo 3: Percorrendo Arrays Multidimensionais

O array_walk() simples visita apenas os elementos do nível superior, portanto em um array aninhado seu callback receberia os arrays internos em vez dos valores folha. Para dados aninhados, use a função complementar array_walk_recursive(), que desce nos sub-arrays e executa seu callback em cada valor folha. Aqui convertemos para maiúsculas todas as strings em um array de dois níveis.

Exemplo PHP 3: Trabalhando com Arrays Multidimensionais

Saída:

Array
(
    [0] => Array
        (
            [0] => APPLE
            [1] => BANANA
            [2] => CHERRY
        )

    [1] => Array
        (
            [0] => ORANGE
            [1] => GRAPE
            [2] => PINEAPPLE
        )

)

array_walk_recursive() percorre a estrutura em profundidade e chama change_case() em cada string folha, preservando a forma aninhada do array enquanto converte todos os valores para maiúsculas.

Armadilhas comuns

• Esquecer o &. Se o primeiro parâmetro do seu callback não for por referência (function (&$value)), suas modificações serão silenciosamente descartadas. Este é o erro mais comum com array_walk().
• Retornar um valor não tem efeito. array_walk() ignora o que quer que seu callback retorne. Ele apenas escreve de volta as alterações feitas através do parâmetro de referência. Se você quiser construir uma cópia transformada, use array_map().
• A ordem dos parâmetros do callback é ($value, $key) — valor primeiro, depois chave. Isso é o oposto do que alguns desenvolvedores esperam.
• Você não pode adicionar ou remover chaves. Definir $array = null dentro do callback, ou alterar a estrutura do array durante o percurso, leva a um comportamento indefinido. Use array_walk() apenas para transformar valores no lugar.

array_walk() vs. array_map() vs. foreach

Use array_walk() quando quiser manter o mesmo array e alterar seus valores no lugar, ou quando precisar que cada callback receba tanto o valor quanto a chave. Escolha array_map() quando quiser um array novo e deixar a fonte intacta.

Conclusão

array_walk() aplica um callback a cada elemento de um array no lugar, tornando-o uma forma limpa de transformar valores, executar efeitos colaterais por elemento ou processar pares chave/valor sem escrever um loop explícito. Lembre-se de receber o valor por referência quando pretender modificá-lo, use array_walk_recursive() em arrays aninhados e prefira array_map() quando preferir construir um novo array em vez de mutar o original. Para mais informações sobre iteração em arrays, veja arrays PHP e o loop foreach.

Prática