rewind()

Introdução

Ao abrir um arquivo em PHP, o sistema mantém o controle de um ponteiro de arquivo — uma posição interna que indica onde ocorrerá a próxima leitura ou escrita. Cada vez que você lê com fgets() ou fread(), esse ponteiro avança. A função rewind() envia o ponteiro de volta ao início absoluto do arquivo (byte 0), permitindo que você o leia novamente desde o começo sem precisar fechar e reabrir o arquivo.

Este capítulo explica o que rewind() faz, sua sintaxe e valor de retorno, e quando utilizá-la em vez de fseek().

Sintaxe

rewind(resource $stream): bool

• $stream — um ponteiro de arquivo retornado por fopen() (ou um recurso de stream similar). O stream deve ser válido e permitir posicionamento.
• Retorna true em caso de sucesso e false em caso de falha.

Chamar rewind($stream) é equivalente a fseek($stream, 0): ambos movem o ponteiro para o início do arquivo. Use ftell() a qualquer momento para ler a posição atual do ponteiro.

Nota: Em streams abertos no modo de acréscimo ('a' ou 'a+'), o ponteiro de leitura é movido para o início, mas as escritas ainda são acrescentadas ao final do arquivo.

Exemplo: releitura de um arquivo desde o início

Após ler parte de um arquivo, rewind() permite recomeçar do início:

<?php

$handle = fopen('notes.txt', 'r');

// Read the first line — this advances the pointer
echo fgets($handle);                       // e.g. "First line"
echo 'Pointer is at: ' . ftell($handle);   // a non-zero byte offset

// Send the pointer back to the beginning
rewind($handle);
echo 'After rewind: ' . ftell($handle);    // 0

// Re-read the same first line
echo fgets($handle);                        // "First line" again

fclose($handle);

O primeiro fgets() lê uma linha e deixa o ponteiro em algum ponto do arquivo, por isso ftell() reporta um deslocamento diferente de zero. Após rewind(), ftell() retorna 0, e a próxima leitura começa novamente pelo primeiro byte.

Quando usar rewind()

• Duas passagens pelo mesmo arquivo. Por exemplo, contar as linhas de um arquivo e depois percorrê-lo novamente para processá-las — sem reabrir o arquivo.
• Reiniciar após escrita. Você escreve em um stream temporário, depois usa rewind() e lê o que acabou de escrever.
• Releitura de um stream cujo handle você possui, como php://memory ou php://temp.

Use fseek() quando precisar ir para um deslocamento arbitrário em vez do início absoluto. Para handles de diretório, o equivalente de reinicialização é rewinddir().

Armadilhas comuns

• Streams sem suporte a posicionamento. Alguns streams (sockets de rede, determinados pipes) não podem ser rebobinados; rewind() retorna false. Sempre verifique o valor de retorno se o stream pode não suportar posicionamento.
• Confundir os ponteiros de leitura e escrita no modo de acréscimo. No modo 'a'/'a+', rebobinar não permite sobrescrever a partir do início — os novos dados ainda vão para o final.
• Esquecer que as leituras ainda avançam o ponteiro. rewind() apenas redefine a posição; o próximo fgets()/fread() irá movê-la novamente para frente.

Conclusão

rewind() reposiciona o ponteiro de arquivo para o início do arquivo, permitindo que você o leia novamente desde o começo. Retorna true em caso de sucesso e false em caso de falha, e se comporta como fseek($stream, 0). Combina naturalmente com fopen(), fgets(), ftell() e fseek() quando você precisa fazer mais de uma passagem pelo mesmo arquivo ou stream.

Prática