fseek()

Quando o PHP lê ou escreve em um arquivo, mantém um cursor interno — o indicador de posição do arquivo — que marca onde ocorrerá a próxima leitura ou escrita. Normalmente, esse cursor avança automaticamente à medida que você chama fread() ou fwrite(). A função fseek() permite movê-lo manualmente para qualquer posição em bytes, para que você possa retroceder, avançar ou reler parte de um arquivo sem fechá-lo e reabri-lo.

Este capítulo aborda a sintaxe de fseek(), os três modos de whence, seu valor de retorno e padrões práticos como ler um registro em um deslocamento conhecido e avançar além do fim de um arquivo.

Sintaxe

fseek(resource $stream, int $offset, int $whence = SEEK_SET): int

fseek() retorna 0 em caso de sucesso e -1 em caso de falha. Ele não retorna a nova posição — use ftell() para isso.

Os três modos de whence

A constante $whence determina a partir de onde o deslocamento é contado:

<?php
fseek($file, 10);            // 10 bytes from the start (SEEK_SET is implied)
fseek($file, 5, SEEK_CUR);   // 5 bytes forward from where we are now
fseek($file, -4, SEEK_END);  // 4 bytes before the end of the file

Um exemplo prático

Vamos criar um arquivo, depois saltar para o byte 6 e ler a partir dali. Como escrevemos e lemos no mesmo script, o exemplo é completamente autossuficiente:

<?php

$filename = 'demo.txt';

// Create a file with known contents.
file_put_contents($filename, 'Hello, World!');

$file = fopen($filename, 'r');

fseek($file, 7, SEEK_SET);   // move the cursor to byte 7
$data = fread($file, 5);     // read 5 bytes: W, o, r, l, d
echo $data;                  // World

fclose($file);

A string 'Hello, World!' é armazenada como bytes H(0) e(1) l(2) l(3) o(4) ,(5) (6) W(7) o(8) r(9) l(10) d(11) !(12). Avançar para o byte 7 posiciona o cursor em W, e ler 5 bytes exibe World.

Sempre verifique o valor de retorno

Como fseek() retorna 0 para sucesso e -1 para falha, compare-o explicitamente. Uma verificação de veracidade genérica está errada aqui — 0 é falso:

<?php

$file = fopen('demo.txt', 'r');

if (fseek($file, 7) === -1) {
    echo "Seek failed";
} else {
    echo "Seek succeeded";   // Seek succeeded
}

fclose($file);

Pontos de atenção

• Nem todo stream é buscável. Pipes, sockets de rede e o stream php://stdin não suportam busca; fseek() retorna -1 neles.
• Buscar além do fim é permitido. Com um arquivo aberto para escrita, você pode usar fseek() além do fim atual e depois escrever — o espaço vazio é preenchido com bytes \0 (null), criando uma região esparsa.
• Cuidado ao usar SEEK_CUR no modo de acréscimo. Arquivos abertos com o modo 'a' sempre escrevem no final independentemente do cursor; fseek() afeta apenas as leituras nesse modo.
• fseek() limpa o sinalizador de fim de arquivo, portanto retroceder permite ler dados já percorridos sem reabrir o arquivo.

Funções relacionadas

• ftell() — retorna a posição atual do cursor (o complemento de fseek()).
• rewind() — atalho para fseek($file, 0).
• fread() / fwrite() — ler ou escrever a partir do cursor.
• fopen() / fclose() — abrir e fechar o stream.

Consulte o capítulo Manipulação de Arquivos PHP para uma visão mais ampla.

Conclusão

fseek() oferece acesso aleatório a um arquivo: mova o cursor com um $offset medido a partir de SEEK_SET, SEEK_CUR ou SEEK_END, e então leia ou escreva a partir da nova posição. Lembre-se de verificar o valor de retorno -1, use ftell() para saber onde está e tenha em mente que nem todo stream suporta busca.

Prática