fpassthru()

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

La función fpassthru() es una función integrada de PHP que lee todos los datos restantes de un puntero de archivo abierto — comenzando desde la posición actual del puntero y continuando hasta el final del archivo (EOF) — y los escribe directamente en el flujo de salida (lo que recibe el navegador o la terminal). Dado que transmite los datos en fragmentos en lugar de cargar todo el archivo en una cadena, es muy adecuada para enviar archivos grandes sin agotar el límite de memoria de PHP.

Esta página cubre la sintaxis de la función, un patrón de uso paso a paso, un ejemplo real de descarga de archivos, cómo difiere de readfile() y los detalles importantes que conviene conocer.

Devuelve el número de bytes escritos en la salida en caso de éxito, o false en caso de error.

Aquí está la sintaxis básica de la función fpassthru():

La sintaxis PHP de fpassthru()

fpassthru(resource $stream): int|false

Donde $stream es un puntero de archivo que debe ser válido y estar ya abierto (normalmente el valor de retorno de fopen()). Una vez que fpassthru() retorna, el puntero está en EOF y los datos han sido consumidos — no es posible leerlos de nuevo sin rebobinar.

¿Cómo usar la función fpassthru()?

Usar la función fpassthru() es sencillo. Estos son los pasos a seguir:

1. Abra el archivo con fopen() y asegúrese de que el puntero de archivo esté en la posición inicial deseada.
2. Llame a fpassthru() con el puntero de archivo. Leerá hasta EOF y escribirá en el flujo de salida.
3. Verifique el valor de retorno para confirmar el éxito y luego cierre el archivo con fclose().

Aquí hay un fragmento de código de ejemplo que demuestra cómo usar la función fpassthru():

¿Cómo usar la función fpassthru()?

<?php

$filename = 'largefile.txt';
$file = fopen($filename, 'r');
if ($file) {
   if (fpassthru($file) === false) {
      echo "Error reading file!";
   }
   fclose($file);
} else {
   echo "Unable to open file!";
}

En este ejemplo, abrimos el archivo largefile.txt usando la función fopen() en modo de solo lectura. Comprobamos si el archivo se abrió correctamente usando una instrucción if, y si fue así, enviamos su contenido al flujo de salida estándar con fpassthru(). Verificamos el valor de retorno para manejar posibles errores de lectura y luego cerramos el identificador con fclose().

Nota sobre el búfer de salida: Si el búfer de salida de PHP está activo (por ejemplo, mediante ob_start()), fpassthru() escribirá directamente en el búfer de salida actual en lugar de enviar los datos inmediatamente al navegador.

Lectura desde la posición actual, no desde el inicio del archivo

Un detalle clave es que fpassthru() comienza en la posición actual del puntero. Si ya ha leído parte del archivo (por ejemplo con fgets() o fread()), solo se envían los bytes restantes. Esto le permite leer una cabecera por su cuenta y transmitir el resto:

<?php

$file = fopen('php://temp', 'r+');
fwrite($file, "HEADER\nbody-line-1\nbody-line-2\n");
rewind($file);

// Consume the first line manually.
echo "First line: " . fgets($file);

// Stream everything left after the pointer.
fpassthru($file);
fclose($file);

Esto imprime:

First line: HEADER
body-line-1
body-line-2

La línea HEADER no se repite, porque el puntero ya había avanzado más allá de ella cuando se ejecutó fpassthru().

Enviar un archivo como descarga

El uso más común en producción de fpassthru() es transmitir un archivo al navegador como descarga. Configure las cabeceras adecuadas, abra el archivo en modo binario ('rb') y deje que fpassthru() envíe los bytes:

<?php

$path = '/var/www/files/report.pdf';

if (is_readable($path)) {
   header('Content-Type: application/pdf');
   header('Content-Disposition: attachment; filename="report.pdf"');
   header('Content-Length: ' . filesize($path));

   $file = fopen($path, 'rb');
   fpassthru($file);
   fclose($file);
   exit;
}

http_response_code(404);
echo 'File not found.';

El modo 'rb' es importante en Windows, donde el modo de texto predeterminado corrompería datos binarios como imágenes, PDFs o archivos comprimidos. En Linux y macOS el indicador b es inofensivo, por lo que es una buena práctica incluirlo siempre en las descargas.

fpassthru() vs. readfile()

Ambas funciones transmiten un archivo a la salida, pero operan en niveles diferentes:

Si simplemente desea enviar un archivo completo y no tiene un identificador abierto, readfile() es más conciso. Use fpassthru() cuando ya tenga un puntero de archivo o necesite saltarse una parte del flujo primero.

Conclusión

La función fpassthru() es una herramienta útil en PHP para leer archivos grandes sin cargarlos en memoria. Siguiendo los pasos descritos en esta guía, puede usar fácilmente la función fpassthru() en sus proyectos PHP para leer el contenido de los archivos desde la posición actual del puntero y enviarlo al flujo de salida estándar.

Práctica