reset()

Todo array PHP mantém um ponteiro interno oculto que marca o elemento "atual". Funções como current(), key(), next() e prev() leem e movem esse ponteiro. Após percorrer um array, o ponteiro fica posicionado no final (ou em algum ponto intermediário) e a próxima leitura retorna o elemento errado. A função reset() rebobina esse ponteiro de volta ao primeiro elemento para que você possa começar novamente.

Este artigo explica como o ponteiro interno funciona, o que reset() retorna, onde as pessoas costumam se enganar e como ela se encaixa com as demais funções de ponteiro de array.

O que é reset()?

reset() é uma função PHP embutida que move o ponteiro interno de um array para o primeiro elemento e retorna o valor desse elemento. É o oposto de end(), que move o ponteiro para o último elemento.

É fundamental notar que reset() modifica o ponteiro do array — por isso sua assinatura recebe o array por referência (&$array). Você passa uma variável, não um literal, e reset() altera o estado do ponteiro dessa variável diretamente.

Sintaxe

reset(array &$array): mixed

Parâmetros

Valor de retorno

reset() retorna o valor do primeiro elemento do array, ou false se o array estiver vazio.

Uma armadilha sutil: como um array vazio retorna false, não é possível distinguir de forma confiável "array vazio" de "primeiro elemento é literalmente false" apenas verificando o valor de retorno. Se precisar dessa distinção, verifique o array com empty() ou count() primeiro.

Exemplos

Vamos ver como reset() se comporta com diferentes tipos de arrays.

Exemplo 1: Redefinindo o ponteiro de um array numérico

Exemplo de redefinição do ponteiro de um array numérico em PHP

Neste exemplo, temos um array de cores. Chamamos a função reset() para redefinir o ponteiro para o início do array. Em seguida, chamamos current() para obter o primeiro elemento, que é 'red'.

Exemplo 2: Redefinindo o ponteiro de um array associativo

Exemplo de redefinição do ponteiro de um array associativo em PHP

Neste exemplo, temos um array associativo com os dados de uma pessoa. Chamamos a função reset() para redefinir o ponteiro para o início do array. Em seguida, chamamos key() e current() para obter o par chave-valor do primeiro elemento.

Exemplo 3: Por que reset() é importante após iterar

Esta é a razão mais comum no mundo real para chamar reset(). Funções que movem o ponteiro (next(), end(), um loop while manual) deixam-no parado. Sem reset(), a próxima leitura continua de onde parou:

<?php

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

// Advance the pointer to the end
end($colors);          // pointer now at 'blue'
echo current($colors); // outputs 'blue'

echo "\n";

// Rewind it
reset($colors);
echo current($colors); // outputs 'red'

reset() também retorna o primeiro valor, então você pode capturá-lo diretamente: $first = reset($colors); resulta em 'red'.

reset() vs. foreach

Um ponto frequente de confusão: um loop foreach não usa o ponteiro interno do array. O PHP itera sobre uma cópia interna, portanto o ponteiro não é alterado e você não precisa chamar reset() após um foreach:

<?php

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

foreach ($colors as $color) {
    // ... do something
}

// Pointer was never moved by foreach
echo current($colors); // outputs 'red'

Você só precisa de reset() quando você (ou uma função que você chama) avança o ponteiro com as funções baseadas em ponteiro. Veja foreach para entender como o loop realmente funciona.

Armadilhas comuns

• Passe uma variável, não um literal. Como o argumento é por referência, reset(['a', 'b']) gera um erro no PHP moderno. Atribua o array a uma variável primeiro.
• reset() modifica o estado. Se outra parte do seu código depende da posição atual do ponteiro, chamar reset() irá alterá-la silenciosamente. Passe uma cópia se precisar preservar o ponteiro original.
• false é ambíguo. Um retorno false pode significar "array vazio" ou "primeiro valor é false". Use empty($array) como proteção quando isso importar.

Funções relacionadas

Conclusão

reset() rebobina o ponteiro interno de um array para o primeiro elemento e retorna o valor desse elemento. Recorra a ela sempre que uma operação anterior (next(), end(), ou um loop manual de ponteiro) tiver deixado o ponteiro em algum lugar diferente do início e você precisar começar a leitura desde o topo. Lembre-se de que foreach não toca o ponteiro, que o argumento deve ser uma variável e que um retorno false é ambíguo para arrays vazios.

Prática