ftell()

O que é a Função ftell()?

A função ftell() é uma função embutida do PHP que retorna a posição atual do ponteiro de arquivo — o deslocamento em bytes, contado a partir do início do arquivo, onde ocorrerá a próxima leitura ou escrita. Todo identificador de arquivo aberto mantém um cursor interno; fread(), fwrite() e fgets() o avançam, enquanto fseek() e rewind() o movem explicitamente. ftell() simplesmente informa onde esse cursor está no momento, sem alterá-lo.

Saber o deslocamento é útil quando você precisa registrar onde está num arquivo (para retomar depois com fseek()), medir quantos bytes já foram consumidos, ou detectar o fim de um registro em um arquivo de largura fixa ou binário.

Esta página cobre a sintaxe, um exemplo executável, o valor que ftell() retorna, armadilhas comuns (modo de acréscimo, streams) e como ela se relaciona com as outras funções de ponteiro de arquivo.

Sintaxe

ftell(resource $stream): int|false

$stream deve ser um ponteiro de arquivo retornado por fopen() (ou por uma função como fsockopen()). A função retorna a posição como um deslocamento inteiro em bytes, ou false em caso de falha — por exemplo, se o stream não for buscável. Como 0 (o início do arquivo) é um resultado válido porém "falsy", sempre teste o valor retornado com ===:

$pos = ftell($file);
if ($pos === false) {
    // could not determine the position
}

Como Usar a Função ftell()

O fluxo típico é:

1. Abra o arquivo com fopen() no modo necessário.
2. Leia ou escreva no arquivo para que o ponteiro avance.
3. Chame ftell() com o ponteiro de arquivo para ler sua posição.
4. Use esse deslocamento — por exemplo, armazene-o ou passe-o para fseek().
5. Feche o arquivo com fclose().

O exemplo abaixo é completamente autocontido: ele grava um arquivo temporário primeiro, para que você possa executá-lo sem precisar preparar nenhum dado.

<?php

// Create a temporary file with known contents.
$filename = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($filename, 'Hello, World! This is a test.');

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

echo "Start position: " . ftell($file) . "\n";   // 0

fread($file, 5);                                  // read "Hello"
echo "After reading 5 bytes: " . ftell($file) . "\n";  // 5

fread($file, 5);                                  // read ", Wor"
echo "After reading 5 more: " . ftell($file) . "\n";   // 10

rewind($file);                                    // jump back to the start
echo "After rewind: " . ftell($file) . "\n";      // 0

fseek($file, 7);                                  // jump to byte 7
echo "After fseek to 7: " . ftell($file) . "\n";  // 7
echo "Next 5 bytes: " . fread($file, 5) . "\n";   // "World"

fclose($file);
unlink($filename);

Saída:

Start position: 0
After reading 5 bytes: 5
After reading 5 more: 10
After rewind: 0
After fseek to 7: 7
Next 5 bytes: World

Cada fread() avança o ponteiro pelo número de bytes efetivamente lidos, então ftell() cresce de 0 para 5 e depois para 10. rewind() o redefine para 0, e fseek($file, 7) o move diretamente para o byte 7, onde a palavra World começa.

Modo de Acréscimo: Uma Armadilha Comum

Quando um arquivo é aberto em modo de acréscimo ('a' ou 'a+'), cada escrita vai para o fim do arquivo independentemente de onde o ponteiro está. ftell() pode reportar 0 logo após a abertura, mesmo que as escritas acabem no final — seu valor de retorno não descreve de forma confiável onde a próxima escrita ocorrerá no modo de acréscimo. Se precisar de posições precisas, abra o arquivo com 'r+', 'w+' ou 'c+' e use seek explicitamente.

Da mesma forma, streams não buscáveis (como alguns streams de rede ou pipe) não conseguem reportar uma posição significativa e ftell() retorna false para eles.

Funções Relacionadas

ftell() raramente funciona sozinha. Ela faz parte de um pequeno conjunto de funções de ponteiro de arquivo:

• fopen() — abre um arquivo e obtém o ponteiro que ftell() lê.
• fread() — lê bytes e avança o ponteiro.
• fwrite() — escreve bytes e avança o ponteiro.
• fseek() — move o ponteiro para uma posição absoluta ou relativa; use em conjunto com ftell() para salvar e restaurar deslocamentos.
• rewind() — redefine o ponteiro para o início (equivalente a fseek($file, 0)).
• fclose() — fecha o arquivo quando você terminar.

Para uma visão geral mais ampla, consulte Manipulação de Arquivos PHP.

Conclusão

A função ftell() informa o deslocamento em bytes atual de um ponteiro de arquivo sem movê-lo, o que a torna a companheira natural de fseek() e rewind() para navegar em arquivos. Lembre-se de comparar seu resultado com === false (pois 0 é um deslocamento válido), e esteja ciente de que o modo de acréscimo e streams não buscáveis não retornam posições confiáveis.

Prática