next()

A Função PHP next()

Todo array PHP possui um ponteiro interno que marca um elemento como o "atual". A função next() move esse ponteiro uma posição à frente e retorna o valor em que ele aterrissa. Ela faz parte de uma pequena família de funções de ponteiro — reset(), current(), prev() e end() — que permitem percorrer um array passo a passo sem escrever seu próprio contador de índice. Este guia explica exatamente o que next() retorna, como altera o ponteiro e os casos extremos que costumam pegar as pessoas de surpresa.

Sintaxe e valor de retorno

next(array &$array): mixed

Três detalhes decorrem dessa assinatura:

• O array é passado por referência (&$array). next() não entrega um novo array — ela muta o ponteiro interno do array que você passa.
• Ela retorna o valor do próximo elemento, não do atual. Para ler o elemento sob o ponteiro sem movê-lo, use current().
• No final do array ela retorna false e estaciona o ponteiro além do último elemento. Todas as chamadas subsequentes também retornam false.

Quando um script acessa um array pela primeira vez, o ponteiro está no primeiro elemento. Portanto, o próprio primeiro next() já retorna o segundo elemento — uma fonte frequente de erros de índice deslocado por um.

Um exemplo básico de next()

O trecho abaixo lê o primeiro elemento com current(), depois avança duas vezes. A última chamada ultrapassa o final e retorna false:

A saída é:

apple
banana
cherry
bool(false)

Percorrendo um array com next()

Um padrão comum é chamar reset() primeiro (para garantir que o ponteiro está no início), imprimir o primeiro elemento e depois iterar com next() até que ele retorne false:

Isso imprime:

red
green
blue

Note a comparação estrita !== false — a próxima seção explica por que uma verificação frouxa é perigosa.

A armadilha dos valores falsos

next() retorna false no final do array, mas também retorna false quando o valor real de um elemento é false, 0, "" ou null. Uma condição frouxa como while (next($array)) portanto para assim que encontra um desses valores:

Como next() retorna 0 para o segundo elemento, o corpo do laço nunca executa — a saída é apenas:

done

Para arrays que podem conter valores falsos, prefira foreach (que ignora o ponteiro interno por completo) ou verifique key(), que retorna null apenas no final genuíno do array.

Como next() se relaciona com as outras funções de ponteiro

next() raramente trabalha sozinha. Ela se combina com reset(), current(), prev(), end() e key() para oferecer controle manual completo sobre o cursor de um array:

O exemplo abaixo usa end() e prev() junto com next() para mostrar como o ponteiro pode se mover em ambas as direções durante uma passagem:

Saída:

30
20
30
10

Quando usar next()

Para iteração simples sobre todos os elementos, um laço foreach é mais claro e seguro — ele nunca tropeça em valores falsos. Recorra a next() apenas quando precisar realmente de controle explícito, passo a passo, sobre onde o ponteiro está, como ao espiar à frente ainda no meio do laço.

Conclusão

A função next() avança o ponteiro interno de um array um passo à frente e retorna o valor em que ele aterrissa, retornando false ao ultrapassar o último elemento. Por depender do ponteiro interno e sinalizar o fim com false, ela trabalha em conjunto com reset(), current() e prev() — apenas lembre-se da armadilha dos valores falsos, em que uma condição de laço frouxa para cedo demais. Para iteração cotidiana, prefira foreach; escolha next() quando precisar de controle preciso sobre o cursor do array.

Prática