Entendendo Arrays Multidimensionais em PHP

Um array multidimensional em PHP é um array cujos elementos são, por sua vez, outros arrays. Enquanto um array comum (indexado ou associativo) mapeia cada chave para um único valor, um array multidimensional mapeia cada chave para um array aninhado completo — permitindo modelar dados em linhas e colunas, grades, árvores e registros agrupados.

Este capítulo explica como criar arrays bidimensionais e de maior profundidade, como ler e atualizar células individuais, como percorrê-los com foreach e as funções mais comuns para transformá-los. Também aponta os erros que costumam ocorrer quando se passa de arrays planos para arrays aninhados.

O que é um Array Multidimensional?

Um array se torna multidimensional no momento em que um de seus valores é outro array. A dimensão (ou profundidade) é o número de operações de índice necessárias para chegar a um valor escalar:

• $a[0] alcança um valor → unidimensional
• $a[0][1] alcança um valor → bidimensional
• $a[0][1][2] alcança um valor → tridimensional, e assim por diante.

Um array bidimensional é frequentemente visualizado como uma tabela: o array externo contém as linhas, e cada array interno contém as colunas dessa linha. Esse modelo mental é útil, mas lembre-se de que arrays PHP são mapas ordenados, não grades rígidas — as linhas podem ter tamanhos diferentes e as chaves podem ser strings em vez de 0, 1, 2. Não há limite fixo de profundidade, embora dados muito aninhados geralmente indiquem que seria melhor usar objetos ou um banco de dados.

Criando um Array Multidimensional

A forma mais comum é aninhar literais de array. Cada array interno é um elemento do array externo.

Um array 2D de strings (uma grade)

$grid = [
    ["value1", "value2", "value3"],
    ["value4", "value5", "value6"],
    ["value7", "value8", "value9"],
];

No código real, os arrays internos geralmente são associativos, de modo que cada linha se lê como um registro:

Uma lista de registros

$employees = [
    ["name" => "Ann",  "title" => "Engineer", "salary" => 65000],
    ["name" => "Bob",  "title" => "Designer", "salary" => 58000],
    ["name" => "Cara", "title" => "Manager",  "salary" => 72000],
];

Você também pode construir um array incrementalmente, o que é útil quando os dados vêm de um loop ou de uma consulta ao banco de dados:

$matrix = [];
$matrix[0][0] = 1;
$matrix[0][1] = 2;
$matrix[1][0] = 3;
$matrix[1][1] = 4;
// $matrix is now [[1, 2], [3, 4]]

Acessando Elementos

Adicione um conjunto de colchetes por dimensão. O primeiro índice seleciona o elemento externo (a linha); o segundo seleciona o elemento interno (a coluna):

echo $grid[1][2];          // "value6" — row 1, column 2
echo $employees[2]["name"]; // "Cara"

PHP usa índices baseados em zero, portanto, a segunda linha é [1] e a terceira coluna é [2]. Ler uma chave que não existe emite um aviso e retorna null; use isset() ou o operador de coalescência nula para manter a segurança:

$salary = $employees[5]["salary"] ?? 0; // no warning if the row is missing

Percorrendo um Array Multidimensional com Loop

Loops foreach aninhados são a forma idiomática de percorrer um array 2D — o loop externo visita cada linha, e o loop interno visita os valores dessa linha:

$employees = [
    ["name" => "Ann",  "salary" => 65000],
    ["name" => "Bob",  "salary" => 58000],
];

foreach ($employees as $row) {
    foreach ($row as $key => $value) {
        echo "$key: $value\n";
    }
    echo "---\n";
}

Para registros tabulares, muitas vezes é mais limpo desestruturar as chaves internas diretamente:

foreach ($employees as $emp) {
    echo "{$emp['name']} earns {$emp['salary']}\n";
}
// Ann earns 65000
// Bob earns 58000

Modificando Elementos

Atribua pelo caminho completo do índice para atualizar uma única célula, e acrescente uma nova linha com [] ou array_push():

$employees[0]["salary"] = 70000;        // update one field
$employees[] = ["name" => "Dan", "salary" => 60000]; // add a row
array_pop($employees);                   // remove the last row

array_pop() remove e retorna a última linha, portanto, as duas operações acima se cancelam.

Transformando com array_map e array_column

array_map() aplica um callback a cada elemento. Para transformar cada célula, mapeie um array_map interno sobre cada linha:

Converter para maiúsculas todos os valores de um array 2D

$grid = [["a", "b"], ["c", "d"]];

$upper = array_map(function ($row) {
    return array_map("strtoupper", $row);
}, $grid);
// $upper is [["A", "B"], ["C", "D"]]

Quando os arrays internos são registros, array_column() extrai um único campo de cada linha para um array plano — perfeito para extrair uma coluna:

$employees = [
    ["name" => "Ann", "salary" => 65000],
    ["name" => "Bob", "salary" => 58000],
];

$names = array_column($employees, "name"); // ["Ann", "Bob"]
$total = array_sum(array_column($employees, "salary")); // 123000

Erros Comuns

• Índices deslocados por um. $grid[1][2] é a segunda linha, terceira coluna — ambos os índices são baseados em zero.
• Confundir a ordem dos índices. $employees[0]["name"] funciona; $employees["name"][0] não funciona, porque o array externo é indexado por inteiros.
• Chaves indefinidas. Acessar uma linha ou coluna inexistente emite um aviso e retorna null. Use isset() ou ?? default como proteção.
• Funções que precisam de recursão. count($arr) simples conta apenas o nível superior — use count($arr, COUNT_RECURSIVE). Para percorrer todas as folhas, use array_walk_recursive() em vez de array_walk().
• Semântica de cópia. Arrays PHP são copiados por valor, portanto $copy = $original; seguido de edição de $copy[0][0] não altera $original — ao contrário de referências a objetos.

Conclusão

Arrays multidimensionais permitem representar tabelas, grades e registros agrupados aninhando um array dentro de outro. Leia e escreva células individuais com índices [] encadeados, itere com loops foreach aninhados e remodelei dados com array_map(), array_column() e as funções de array recursivas. Para um panorama mais amplo do conjunto de ferramentas de array do PHP, consulte PHP Arrays.

Prática