foreach no PHP: chave e valor, índice e referência

foreach ($array as $value) executa o bloco uma vez para cada elemento, com $value valendo o elemento atual. Para obter a chave também, escreva foreach ($array as $key => $value).

<?php
$colors = ['red', 'green', 'blue'];

foreach ($colors as $color) {
    echo $color, "\n";
}

$ages = ['Ada' => 36, 'Linus' => 28, 'Grace' => 45];

foreach ($ages as $name => $age) {
    echo "$name is $age\n";
}

O foreach funciona com qualquer array, sejam quais forem as chaves, e você nunca precisa controlar um contador ou verificar um tamanho. É o loop que você mais vai escrever em PHP.

Percorrer chaves e valores

Em $key => $value, os nomes são você quem escolhe: $name => $age, $id => $user, $k => $v. Numa lista, as chaves são as posições 0, 1, 2. Num array associativo, são as chaves string que você definiu.

<?php
$config = [
    'host' => 'localhost',
    'port' => 8080,
    'debug' => true,
];

foreach ($config as $key => $value) {
    printf("%-6s = %s\n", $key, var_export($value, true));
}

// Only the keys
foreach (array_keys($config) as $key) {
    echo "key: $key\n";
}

// Keys like "1" become integers
$codes = ["1" => 'one', "01" => 'zero one'];
foreach ($codes as $key => $value) {
    echo gettype($key), " key ", var_export($key, true), " => $value\n";
}

O último loop mostra um detalhe que surpreende: uma chave string que parece um número inteiro, como "1", é guardada como o inteiro 1. "01" não é um inteiro canônico, então continua string.

Obter o índice no foreach

Numa lista, a chave é o índice, então foreach ($items as $i => $item) é tudo de que você precisa. Num array associativo não há posição numérica, então mantenha um contador. Para tratar o primeiro ou o último elemento de outro jeito, compare a chave com array_key_first() ou array_key_last().

<?php
$steps = ['Preheat', 'Mix', 'Bake'];

foreach ($steps as $i => $step) {
    echo "Step ", $i + 1, ": $step\n";   // index starts at 0
}

$scores = ['Ada' => 91, 'Linus' => 78, 'Grace' => 85];
$position = 1;
foreach ($scores as $name => $score) {
    echo "#$position $name ($score)\n";
    $position++;
}

$last = array_key_last($scores);
foreach ($scores as $name => $score) {
    echo $name, $name === $last ? "\n" : ", ";
}

O último loop imprime uma vírgula entre os nomes, mas não depois do último. Para essa tarefa exata, implode(', ', array_keys($scores)) é mais curto; a verificação com array_key_last() serve para quando a última volta precisa de uma lógica diferente, não só de outro separador.

Alterar valores do array no foreach (por referência)

$value é uma cópia. Atribuir a ele não muda nada no array. Para mudar o array, percorra por referência com &$value ou escreva de volta pela chave.

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

foreach ($prices as $price) {
    $price = $price * 2;          // changes the copy only
}
echo implode(', ', $prices), "\n";

foreach ($prices as &$price) {
    $price = $price * 2;          // changes the array
}
unset($price);                    // break the reference (see next section)
echo implode(', ', $prices), "\n";

foreach ($prices as $key => $price) {
    $prices[$key] = $price + 1;   // same effect, no reference
}
echo implode(', ', $prices), "\n";

Os dois funcionam. A versão com a chave não deixa estado escondido depois do loop, e é por isso que muitas equipes a preferem. Para montar um novo array em vez de alterar um, o array_map() é outra opção.

Uma pergunta relacionada: o que acontece se você adicionar elementos durante o loop? Um foreach simples percorre o array como ele estava quando o loop começou, então $prices[] = ... dentro dele não cria voltas extras. Um loop por referência percorre o array vivo e visita os novos elementos.

A pegadinha do unset() com foreach por referência

Depois de foreach ($arr as &$v), a variável $v continua sendo uma referência ao último elemento do array. Se você reutilizar o nome $v depois num loop normal, cada volta escreve nesse último elemento. Rode e olhe o último item:

<?php
$letters = ['a', 'b', 'c'];

foreach ($letters as &$v) {
    $v = strtoupper($v);
}
// missing: unset($v);

foreach ($letters as $v) {
    // each pass assigns to $v, which is still $letters[2]
}

print_r($letters);   // C was overwritten

$fixed = ['a', 'b', 'c'];
foreach ($fixed as &$v) {
    $v = strtoupper($v);
}
unset($v);           // the fix
foreach ($fixed as $v) {
}
print_r($fixed);

O segundo loop atribui A, depois B, depois o próprio valor do último elemento a $letters[2], e na última volta essa posição já guarda B. A correção é uma linha: coloque unset($v); logo depois de cada foreach por referência.

break e continue no foreach

break sai do loop, continue pula para o próximo elemento. Um padrão comum é a busca: percorra até encontrar o que precisa e dê break, para que o resto do array não seja verificado.

<?php
$orders = [
    ['id' => 101, 'status' => 'paid'],
    ['id' => 102, 'status' => 'cancelled'],
    ['id' => 103, 'status' => 'paid'],
    ['id' => 104, 'status' => 'pending'],
];

foreach ($orders as $order) {
    if ($order['status'] === 'cancelled') {
        continue;               // skip this one
    }
    echo "Order {$order['id']}: {$order['status']}\n";
}

$found = null;
foreach ($orders as $order) {
    if ($order['status'] === 'pending') {
        $found = $order;
        break;                  // stop searching
    }
}
echo "First pending: ", $found['id'] ?? 'none', "\n";

Em loops aninhados, break 2 sai do loop interno e do que está em volta dele, e continue 2 pula para a próxima volta do loop externo.

Arrays aninhados e foreach com list()

Linhas de dados são arrays dentro de um array. Percorra as linhas e depois cada linha, ou extraia os campos direto na linha do foreach com desestruturação de array: [$a, $b] para listas, ['key' => $var] para linhas associativas. list($a, $b) é a grafia antiga de [$a, $b].

<?php
$users = [
    ['name' => 'Ada', 'langs' => ['PHP', 'Python']],
    ['name' => 'Linus', 'langs' => ['C']],
];

// Nested foreach
foreach ($users as $user) {
    echo $user['name'], ":";
    foreach ($user['langs'] as $lang) {
        echo " $lang";
    }
    echo "\n";
}

// Destructuring associative rows
foreach ($users as ['name' => $name, 'langs' => $langs]) {
    echo "$name knows ", count($langs), " language(s)\n";
}

// Destructuring list rows (list() is the same as [])
$points = [[1, 2], [3, 5], [8, 13]];
foreach ($points as [$x, $y]) {
    echo "($x, $y) ";
}
echo "\n";
foreach ($points as list($x, $y)) {
    echo $x + $y, " ";
}

A página sobre desestruturação tem mais sobre a sintaxe [...] =, incluindo elementos pulados e padrões aninhados.

Montar uma lista ou tabela HTML com foreach

Num template, a forma com dois pontos foreach (...): com endforeach; mantém o loop legível entre as tags. Este bloco monta uma tabela, e os cabeçalhos das colunas são links: clique num deles na aba Page e o mesmo script roda de novo com $_GET['sort'] definido, então as linhas voltam numa nova ordem.

<?php
$products = [
    ['name' => 'Keyboard', 'price' => 49.0, 'stock' => 12],
    ['name' => 'Mouse', 'price' => 19.5, 'stock' => 40],
    ['name' => 'Monitor', 'price' => 189.0, 'stock' => 3],
    ['name' => 'Cable', 'price' => 6.25, 'stock' => 0],
];

$sort = $_GET['sort'] ?? 'name';
if (!in_array($sort, ['name', 'price', 'stock'], true)) {
    $sort = 'name';
}
usort($products, fn($a, $b) => $a[$sort] <=> $b[$sort]);

$total = 0;
foreach ($products as $p) {
    $total += $p['price'] * $p['stock'];
}
?>
<style>
    table { border-collapse: collapse; font-family: sans-serif; }
    th, td { border: 1px solid #ccc; padding: 4px 10px; }
    .out { color: #999; }
</style>
<table>
    <tr>
        <?php foreach (['name', 'price', 'stock'] as $col): ?>
            <th><a href="?sort=<?= $col ?>"><?= ucfirst($col) ?></a><?= $col === $sort ? ' ▲' : '' ?></th>
        <?php endforeach; ?>
    </tr>
    <?php foreach ($products as $p): ?>
        <tr class="<?= $p['stock'] === 0 ? 'out' : '' ?>">
            <td><?= htmlspecialchars($p['name']) ?></td>
            <td><?= number_format($p['price'], 2) ?></td>
            <td><?= $p['stock'] ?></td>
        </tr>
    <?php endforeach; ?>
</table>
<p>Stock value: <?= number_format($total, 2) ?></p>

Dois hábitos que valem copiar desse bloco: o valor sort da URL é comparado com uma lista de colunas permitidas antes de ser usado, e todo valor impresso no HTML que pode conter texto do usuário passa por htmlspecialchars().

foreach em null, num array vazio ou num objeto

Um array vazio não tem problema: o corpo nunca roda. null, uma string ou um número têm: o PHP imprime um aviso e pula o loop. Para $tags = null; foreach ($tags as $tag) ele imprime:

Warning: foreach() argument must be of type array|object, null given in /var/www/html/index.php on line 4

Isso acontece mais com dados que às vezes faltam, como um campo opcional num JSON decodificado. Use um array vazio como padrão com ??:

foreach ($data['tags'] ?? [] as $tag) {
    echo $tag;
}

O object nessa mensagem é real: um foreach sobre um objeto visita as propriedades visíveis de onde o loop roda (fora da classe, as públicas), com o nome da propriedade como chave. Classes que implementam Iterator ou IteratorAggregate, e generators, decidem por conta própria o que um foreach enxerga.

foreach, for ou array_map

Um jeito rápido de decidir: se o corpo do loop só calcula um novo valor por elemento, array_map(fn($x) => $x * 2, $a) diz isso numa linha. Se ele tem efeitos colaterais (imprimir, salvar, contar várias coisas ao mesmo tempo) ou precisa de break, escreva o foreach.