next()

Introdução

Todo array PHP mantém um ponteiro interno que marca um elemento como "atual". Uma pequena família de funções move esse ponteiro sem precisar escrever um loop: reset(), current(), prev(), end() e next(). Este artigo foca em next() — o que ela retorna, como altera o ponteiro e os casos especiais que costumam causar confusão.

O que a função next() faz

next() avança o ponteiro interno do array uma posição e retorna o valor do elemento em que ele chega. A assinatura é:

next(array &$array): mixed

Alguns aspectos se destacam dessa assinatura:

• O array é passado por referência (&$array). next() não retorna um novo array — ela muta o ponteiro do array passado.
• Ela retorna o valor do próximo elemento, não do atual. Se você quiser o elemento sob o ponteiro sem movê-lo, use current().
• Ao final do array ela retorna false e deixa o ponteiro posicionado após o último elemento. Chamar next() novamente continua retornando false.

Quando um script inicia, o ponteiro está no primeiro elemento, portanto o primeiro next() já retorna o segundo elemento — não o primeiro. Esta é a fonte mais comum de confusão de "erro por um" com next().

Exemplo básico

<?php

$fruits = ['apple', 'banana', 'cherry'];

echo current($fruits) . "\n"; // pointer starts on the first element
echo next($fruits) . "\n";    // move forward, return the second
echo next($fruits) . "\n";    // move forward, return the third
var_dump(next($fruits));      // past the end -> false

Isso produz:

apple
banana
cherry
bool(false)

current() lê o primeiro elemento sem mover o ponteiro, depois cada next() avança um elemento. A última chamada vai além do fim do array e retorna false.

Percorrendo um array com next()

Um padrão comum é começar com reset() (para garantir que o ponteiro esteja no início) e iterar com next() até que retorne false:

<?php

$colors = ['red', 'green', 'blue'];

reset($colors);
echo current($colors) . "\n"; // first element

while (($color = next($colors)) !== false) {
    echo $color . "\n";
}

Saída:

red
green
blue

Note o !== false (comparação estrita). Isso importa — veja a próxima seção.

O problema com valores "falsy"

next() retorna false ao final do array, mas também retorna false se o valor real de um elemento for false, 0, "" ou null. Uma verificação solta como while (next($array)) vai parar antes do tempo quando encontrar um desses valores:

<?php

$data = ['a', 0, 'b'];
reset($data);

// WRONG: stops at the 0, never reaches 'b'
while ($value = next($data)) {
    echo $value . "\n";
}
echo "---\n";

Isso imprime apenas:

---

O loop termina imediatamente porque next() retorna 0 (o segundo elemento), que é falsy. Para arrays que podem conter valores falsy, prefira foreach, que ignora o ponteiro interno completamente, ou use key() para detectar o fim real:

<?php

$data = ['a', 0, 'b'];
reset($data);

do {
    echo current($data) . "\n";
} while (next($data) !== null && key($data) !== null);

Na prática, um foreach simples é a ferramenta certa para iterar sobre todos os elementos; use next() apenas quando precisar de controle manual e passo a passo do ponteiro.

next() e as funções relacionadas de ponteiro

Combinar next() e prev() permite olhar adiante e voltar durante uma única passagem sobre um array.

Conclusão

A função next() avança o ponteiro interno de um array um passo adiante e retorna o valor em que ele chega, ou false quando ultrapassa o fim. Como depende do ponteiro interno e sinaliza o fim com false, ela se combina naturalmente com reset(), current() e prev() — mas tome cuidado com arrays contendo valores falsy, onde uma condição de loop solta vai parar cedo demais. Para iteração simples, prefira foreach; use next() quando precisar de controle explícito sobre onde o ponteiro está.

Prática