each()

Introdução

A função each() era historicamente usada para percorrer um array elemento por elemento, retornando o par chave-valor atual e avançando o ponteiro interno do array. Ela alimentava um idioma comum com laço while para iterar arrays antes que foreach se tornasse o padrão.

Importante: each() foi descontinuada no PHP 7.2 e completamente removida no PHP 8.0. Chamá-la no PHP 8+ lança um Error fatal. Esta página documenta seu comportamento legado para que você possa ler e migrar código antigo — mas nunca escreva código novo com ela. Acesse Alternativas modernas para saber o que usar no lugar.

Esta página aborda o que each() fazia, sua sintaxe e formato de retorno, o comportamento do ponteiro interno que a tornava complicada e como reescrever cada uso com foreach.

Sintaxe

A sintaxe da função each() é a seguinte:

Sintaxe da função Each() em PHP

each(array $array): array|false

A função each() recebe um array como parâmetro e retorna um array ou false em caso de falha.

Parâmetros

O array é passado por referência porque each() o modifica — especificamente, ela move o ponteiro interno do array para frente a cada chamada.

Valor de retorno

A cada chamada, each() retorna um array de quatro elementos, com chaves numéricas e string apontando para os mesmos dados:

Quando o ponteiro ultrapassa o último elemento, each() retorna false — o que interrompe o laço while clássico.

Uso

O idioma clássico combinava each() com um laço while. Cada iteração obtinha um par e avançava o ponteiro; quando não havia mais pares, each() retornava false e o laço terminava.

Laço each() legado (PHP 7.x e anteriores)

<?php
// Legacy PHP 7.x example. This will throw a fatal Error in PHP 8.0+.
$array = ["one" => 1, "two" => 2, "three" => 3];

while ($element = each($array)) {
    echo $element['key'] . ' => ' . $element['value'] . "\n";
}
// Output:
// one => 1
// two => 2
// three => 3

Definimos um array associativo e chamamos each() repetidamente dentro de um while. Cada chamada retorna o par atual (acessível como $element['key'] / $element['value']) e avança o ponteiro, até que each() retorne false.

O problema do ponteiro interno

Como each() consome o ponteiro interno, um array só pode ser percorrido completamente uma vez. Para iterar uma segunda vez, era necessário chamar reset() primeiro para rebobinar o ponteiro ao início. Esquecer isso era uma fonte frequente de bugs do tipo "meu laço não faz nada" — e é uma das razões pelas quais each() foi eventualmente removida em favor de foreach, que usa seu próprio iterador e nunca perturba o array.

Equivalente moderno no PHP 8+

Todo o padrão while (each()) se resume a um único foreach mais claro:

<?php
$array = ["one" => 1, "two" => 2, "three" => 3];

foreach ($array as $key => $value) {
    echo $key . ' => ' . $value . "\n";
}
// Output:
// one => 1
// two => 2
// three => 3

foreach é mais conciso, não toca o ponteiro interno (então o array permanece reutilizável) e é o único dos dois que funciona no PHP 8+.

each() vs. funções similares de array

each() é frequentemente agrupada com outras ferramentas de iteração, mas cada uma faz algo distinto:

Se você precisar do controle manual de ponteiro que each() oferecia, combine current(), key(), next() e reset() — essas funções ainda estão disponíveis no PHP 8+.

Status legado e alternativas modernas

A função each() está descontinuada (PHP 7.2) e removida (PHP 8.0). Para todo código novo:

• Iterando um array? Use foreach.
• Transformando valores em um novo array? Use array_map().
• Modificando elementos no lugar? Use array_walk().
• Precisa de passos manuais? Use current() + next() + reset().

Conclusão

each() foi a forma preferida de percorrer um array e obter pares chave-valor, mas sua dependência do ponteiro interno a tornava propensa a erros, e o PHP 8.0 a removeu completamente. Trate-a como história somente leitura: reconheça-a em código legado e substitua-a por foreach — que é mais seguro, mais rápido e o padrão moderno.

Prática