Array multidimensional em PHP: arrays aninhados e loops

Um array multidimensional é um array cujos elementos são arrays. Você o lê com um par de colchetes por nível: $grid[1][2] é a linha 1, coluna 2, e $users[0]['name'] é o nome no primeiro registro.

<?php
$grid = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
];

echo $grid[1][2], "\n";   // row 1, column 2

$users = [
    ['name' => 'Ada',   'role' => 'admin'],
    ['name' => 'Linus', 'role' => 'editor'],
];

echo $users[0]['name'], "\n";
echo $users[1]['role'], "\n";

$grid[2][0] = 70;         // change a nested value
echo implode(' ', $grid[2]), "\n";

O segundo formato, uma lista de registros com campos nomeados, é o que você mais vai encontrar: é o que uma consulta ao banco, uma resposta JSON decodificada ou um arquivo CSV processado normalmente entregam. Cada registro é um array associativo.

Criar arrays aninhados

O aninhamento pode ir tão fundo quanto você precisar, e os níveis podem misturar chaves numéricas e string. Um array de configuração é um exemplo comum: seções com nome, cada uma com configurações ou listas.

<?php
$config = [
    'db' => [
        'host' => 'localhost',
        'port' => 3306,
    ],
    'admins' => ['ada', 'grace'],
    'features' => [
        'search' => ['enabled' => true, 'limit' => 20],
    ],
];

echo $config['db']['host'], "\n";
echo $config['admins'][1], "\n";
echo $config['features']['search']['limit'], "\n";

Adicionar linhas e valores aninhados

$rows[] = [...] acrescenta uma linha inteira. $arr['key'][] = $value acrescenta dentro de uma lista aninhada, e o PHP cria o array interno na primeira vez, então agrupar valores não exige preparação.

<?php
$orders = [
    ['customer' => 'Ada',   'item' => 'book'],
    ['customer' => 'Linus', 'item' => 'pen'],
    ['customer' => 'Ada',   'item' => 'lamp'],
];

$orders[] = ['customer' => 'Grace', 'item' => 'mug'];   // add a row

$byCustomer = [];
foreach ($orders as $order) {
    $byCustomer[$order['customer']][] = $order['item'];  // inner array created on first use
}

print_r($byCustomer);

Percorrer um array multidimensional

Use um foreach por nível. Para uma lista de registros, um loop costuma bastar, porque você lê os campos pelo nome. Para uma grade, o loop interno percorre as células de cada linha.

<?php
$students = [
    ['name' => 'Ada',   'scores' => [90, 85, 99]],
    ['name' => 'Linus', 'scores' => [70, 88, 79]],
];

foreach ($students as $student) {
    $average = array_sum($student['scores']) / count($student['scores']);
    echo $student['name'], ": ", round($average, 1), "\n";
}

$grid = [[1, 2, 3], [4, 5, 6]];
foreach ($grid as $r => $row) {
    foreach ($row as $c => $cell) {
        echo "[$r][$c]=$cell ";
    }
    echo "\n";
}

Montar uma tabela HTML a partir de um array

Um array de linhas vira diretamente uma tabela HTML: as chaves da primeira linha viram o cabeçalho, e cada linha vira um <tr>. Rode e a aba Page mostra a tabela renderizada; mude um valor ou adicione uma linha e rode de novo.

<?php
$products = [
    ['name' => 'Keyboard', 'price' => 49.99, 'stock' => 12],
    ['name' => 'Mouse',    'price' => 19.50, 'stock' => 0],
    ['name' => 'Monitor',  'price' => 189.00, 'stock' => 4],
];
?>
<style>
  table { border-collapse: collapse; font-family: sans-serif; }
  th, td { border: 1px solid #ccc; padding: 6px 12px; text-align: left; }
  .out { color: #b00; }
</style>
<table>
  <tr>
    <?php foreach (array_keys($products[0]) as $heading): ?>
      <th><?= htmlspecialchars(ucfirst($heading)) ?></th>
    <?php endforeach; ?>
  </tr>
  <?php foreach ($products as $product): ?>
    <tr class="<?= $product['stock'] === 0 ? 'out' : '' ?>">
      <td><?= htmlspecialchars($product['name']) ?></td>
      <td><?= number_format($product['price'], 2) ?></td>
      <td><?= $product['stock'] ?></td>
    </tr>
  <?php endforeach; ?>
</table>

A forma foreach (...): ... endforeach; é o mesmo loop escrito para templates, para que o HTML continue legível.

Pegar uma coluna de todas as linhas

array_column() extrai um campo de cada linha para uma lista simples. Passe um terceiro argumento para indexar o resultado por outro campo, o que transforma uma lista de registros numa tabela de consulta.

<?php
$users = [
    ['id' => 3, 'name' => 'Ada',   'email' => 'ada@example.com'],
    ['id' => 7, 'name' => 'Linus', 'email' => 'linus@example.com'],
    ['id' => 9, 'name' => 'Grace', 'email' => 'grace@example.com'],
];

print_r(array_column($users, 'name'));
print_r(array_column($users, 'email', 'id'));   // id => email

$byId = array_column($users, null, 'id');       // id => whole row
echo $byId[7]['name'], "\n";

Ordenar linhas por um campo

usort() ordena as linhas com uma função de comparação. O operador spaceship <=> retorna -1, 0 ou 1, exatamente o que o usort() espera. Troque $a e $b para ordenar em ordem decrescente.

<?php
$players = [
    ['name' => 'Ada',   'points' => 120],
    ['name' => 'Linus', 'points' => 95],
    ['name' => 'Grace', 'points' => 140],
];

usort($players, fn($a, $b) => $b['points'] <=> $a['points']);   // highest first

foreach ($players as $rank => $player) {
    echo $rank + 1, ". {$player['name']} ({$player['points']})\n";
}

echo count($players), " rows, ", count($players, COUNT_RECURSIVE), " elements in total\n";

count($players, COUNT_RECURSIVE) conta as 3 linhas mais os 6 campos dentro delas, e é por isso que imprime 9.

Erro comum: ler uma chave profunda que pode não existir

Ler $config['cache']['ttl'] quando não há chave cache imprime Warning: Undefined array key "cache", seguido de Warning: Trying to access array offset on null para o próximo nível. O operador ?? verifica a cadeia inteira de uma vez e nunca avisa, então é o jeito seguro de ler valores aninhados opcionais.

<?php
$config = ['db' => ['host' => 'localhost']];

$ttl  = $config['cache']['ttl'] ?? 60;          // missing at the first level
$port = $config['db']['port'] ?? 3306;          // missing at the second level
$host = $config['db']['host'] ?? '127.0.0.1';   // present

echo "$ttl $port $host\n";
var_dump(isset($config['db']['host']));