rewind()

Introdução

Quando você lê um arquivo em PHP, um ponteiro de arquivo interno rastreia sua posição atual. Cada leitura avança o ponteiro, então ao atingir o final do arquivo, leituras adicionais não retornam nada. A função rewind() move esse ponteiro de volta ao byte 0 — o início absoluto — permitindo que você leia o mesmo arquivo novamente sem fechá-lo e reabri-lo.

Esta página explica o que rewind() faz, sua sintaxe e valor de retorno, quando utilizá-la, as armadilhas comuns e exemplos executáveis que você pode adaptar.

O que é o ponteiro de arquivo

Pense no ponteiro de arquivo como um cursor dentro do arquivo aberto. Funções como fread(), fgets() e fgetcsv() leem a partir desse cursor e o movem para frente pelo número de bytes consumidos. Você pode inspecionar o cursor com ftell() e movê-lo para uma posição arbitrária com fseek().

rewind($handle) é o atalho conveniente para "voltar ao início" — é equivalente a fseek($handle, 0).

Sintaxe

rewind(resource $handle): bool

• $handle — um recurso de ponteiro de arquivo que ainda está aberto, tipicamente retornado por fopen(). Deve apontar para um stream que pode ser reposicionado.
• Retorna true em caso de sucesso e false em caso de falha.

Por que e quando usar

Use rewind() sempre que precisar ler ou processar o mesmo arquivo aberto mais de uma vez em uma única execução de script:

• Contar e depois processar. Primeira passagem para contar linhas ou validar, segunda passagem para o trabalho real.
• Reler após escrever. Após escrever em um arquivo aberto em modo de leitura/escrita ('w+', 'r+', 'a+'), rebobine antes de ler o que você escreveu.
• Streams em memória. Quando você constrói conteúdo em um stream php://memory ou php://temp, rebobine antes de lê-lo.

Se você apenas lê um arquivo uma vez, não precisa de rewind() de forma alguma.

Exemplos

Exemplo 1: Ler o mesmo arquivo duas vezes

Este exemplo cria um arquivo temporário, lê até o final, depois rebobina e lê novamente.

<?php

// Create a temporary file we can read and write.
$handle = tmpfile();
fwrite($handle, "line one\nline two\n");

// Move to the start so we can read what we just wrote.
rewind($handle);

echo "First read:\n";
echo fread($handle, 1024);

// The pointer is now at the end; reading again gives nothing.
echo "After first read, position: " . ftell($handle) . "\n";

// Rewind and read the whole file again.
rewind($handle);
echo "Second read:\n";
echo fread($handle, 1024);

fclose($handle);

Saída:

First read:
line one
line two
After first read, position: 18
Second read:
line one
line two

O primeiro fread() deixa o ponteiro no byte 18 (o final do arquivo). Sem rewind(), uma segunda leitura retornaria uma string vazia. Após rebobinar, o ponteiro está de volta em 0 e o conteúdo completo está disponível novamente.

Exemplo 2: Escrever, rebobinar e depois reler

Quando um stream é aberto para escrita e leitura, rewind() permite verificar o que você escreveu.

<?php

// php://memory is an in-memory read/write stream.
$handle = fopen('php://memory', 'r+');

fwrite($handle, 'Hello, W3Docs!');

// Without rewind, the pointer sits after the written text,
// so reading now would return an empty string.
rewind($handle);

$content = stream_get_contents($handle);
echo $content; // Hello, W3Docs!

fclose($handle);

Saída:

Hello, W3Docs!

Exemplo 3: Sempre verifique o valor de retorno

rewind() retorna false quando o stream não pode ser reposicionado (por exemplo, um stream de rede ou pipe não-buscável).

<?php

$handle = fopen('php://memory', 'r+');
fwrite($handle, 'data');

if (rewind($handle)) {
    echo "Pointer reset. Position: " . ftell($handle) . "\n";
} else {
    echo "This stream cannot be rewound.\n";
}

fclose($handle);

Saída:

Pointer reset. Position: 0

Armadilhas comuns

• O ponteiro já está no final após a leitura. Este é o principal motivo pelo qual rewind() existe. Se uma segunda leitura não retornar nada, você provavelmente esqueceu de rebobinar.
• Modo de acréscimo ('a' / 'a+'). Rebobinar move o ponteiro de leitura para o início, mas no modo de acréscimo cada fwrite() ainda acrescenta ao final do arquivo independentemente da posição do ponteiro.
• Streams não-buscáveis. Pipes, sockets e alguns streams HTTP não podem ser rebobinados; rewind() retorna false. Verifique o valor de retorno quando a fonte pode não ser buscável.
• Handles fechados. Chamar rewind() em um handle já passado para fclose() gera um aviso. Rebobine antes de fechar.

Funções relacionadas

• fseek() — move o ponteiro para qualquer deslocamento de byte (rewind() é fseek($handle, 0)).
• ftell() — reporta a posição atual do ponteiro.
• fopen() — abre um arquivo ou stream e obtém o handle.
• fread() / fgets() — lê a partir da posição atual.
• fclose() — fecha o handle quando terminar.

Conclusão

rewind() redefine o ponteiro interno de um arquivo aberto para o início, permitindo que você releia ou reprocesse os dados na mesma execução do script. É um wrapper fino e conveniente em torno de fseek($handle, 0). Lembre-se de verificar seu valor de retorno para streams não-buscáveis, tenha em mente o comportamento do modo de acréscimo e rebobine antes de fechar o handle.

Prática