ftell()

¿Qué es la función ftell()?

La función ftell() es una función integrada de PHP que devuelve la posición actual del puntero de archivo — el desplazamiento en bytes contado desde el inicio del archivo, donde ocurrirá la próxima lectura o escritura. Cada manejador de archivo abierto mantiene un cursor interno; fread(), fwrite() y fgets() lo avanzan, mientras que fseek() y rewind() lo mueven de forma explícita. ftell() simplemente informa dónde se encuentra ese cursor actualmente sin modificarlo.

Conocer el desplazamiento es útil cuando necesitas registrar en qué punto del archivo te encuentras (para poder retomar después con fseek()), medir cuántos bytes has consumido hasta el momento, o detectar el final de un registro en un archivo de ancho fijo o binario.

Esta página cubre la sintaxis, un ejemplo ejecutable, el valor que devuelve ftell(), errores comunes (modo anexar, streams) y cómo se relaciona con las demás funciones de puntero de archivo.

Sintaxis

ftell(resource $stream): int|false

$stream debe ser un puntero de archivo devuelto por fopen() (o una función como fsockopen()). La función devuelve la posición como un desplazamiento entero en bytes, o false en caso de error — por ejemplo, si el stream no es buscable. Dado que 0 (el inicio del archivo) es un resultado válido pero "falso", siempre comprueba el valor de retorno con ===:

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

Cómo usar la función ftell()

El flujo típico es:

1. Abre el archivo con fopen() en el modo que necesites.
2. Lee o escribe en el archivo para que el puntero avance.
3. Llama a ftell() con el puntero de archivo para leer su posición.
4. Usa ese desplazamiento — por ejemplo, guárdalo o pásalo a fseek().
5. Cierra el archivo con fclose().

El ejemplo siguiente es completamente autocontenido: primero escribe un archivo temporal para que puedas ejecutarlo tal cual sin preparar ningún dato.

<?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);

Salida:

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 llamada a fread() avanza el puntero el número de bytes que realmente leyó, por lo que ftell() crece de 0 a 5 y luego a 10. rewind() lo reinicia a 0, y fseek($file, 7) lo mueve directamente al byte 7, donde comienza la palabra World.

Modo Anexar: Un Error Común

Cuando un archivo se abre en modo anexar ('a' o 'a+'), cada escritura va al final del archivo independientemente de dónde esté el puntero. ftell() puede devolver 0 justo después de abrir aunque las escrituras vayan al final — su valor de retorno no describe de forma fiable dónde irá la próxima escritura en modo anexar. Si necesitas posiciones precisas, abre el archivo con 'r+', 'w+' o 'c+' y desplázate de forma explícita.

Del mismo modo, los streams no buscables (como algunos streams de red o de tubería) no pueden informar una posición significativa y ftell() devuelve false para ellos.

Funciones Relacionadas

ftell() raramente trabaja sola. Forma parte de una pequeña familia de funciones de puntero de archivo:

• fopen() — abre un archivo y obtiene el puntero que lee ftell().
• fread() — lee bytes y avanza el puntero.
• fwrite() — escribe bytes y avanza el puntero.
• fseek() — mueve el puntero a una posición absoluta o relativa; combínala con ftell() para guardar y restaurar desplazamientos.
• rewind() — reinicia el puntero al inicio (equivalente a fseek($file, 0)).
• fclose() — cierra el archivo cuando hayas terminado.

Para una visión más amplia, consulta Manejo de Archivos en PHP.

Conclusión

La función ftell() informa el desplazamiento en bytes actual de un puntero de archivo sin moverlo, lo que la convierte en el complemento natural de fseek() y rewind() para navegar por archivos. Recuerda comparar su resultado con === false (porque 0 es un desplazamiento válido) y ten en cuenta que el modo anexar y los streams no buscables no devuelven posiciones fiables.

Práctica