fflush()

Introducción a la función fflush() de PHP

La función fflush() en PHP obliga a que cualquier dato que aún esté en el búfer de escritura de un puntero de archivo se escriba en el flujo subyacente de forma inmediata, en lugar de esperar a que el búfer se llene o a que el flujo se cierre.

Cuando llamas a fwrite(), PHP no necesariamente envía los bytes directamente al disco. Por motivos de rendimiento, los datos se acumulan en un búfer en memoria y se escriben en bloques más grandes. Esto suele ser lo deseable, pero a veces necesitas que los datos lleguen ahora: un archivo de log que se puede seguir con tail, un proceso largo que otro proceso está leyendo, o un script que puede interrumpirse antes de finalizar. fflush() es la función que dice "no esperes, escribe lo que tienes".

Esta página cubre la sintaxis, los parámetros, el valor de retorno y varios ejemplos ejecutables, además de los errores comunes que suelen cometer los desarrolladores, incluida la diferencia crucial entre fflush() y la sincronización de disco a nivel del sistema operativo.

Sintaxis

La sintaxis de la función fflush() es la siguiente:

Sintaxis PHP de fflush()

bool fflush ( resource $stream )

• stream: el puntero de archivo que se va a vaciar

Parámetros

La función fflush() acepta un parámetro obligatorio:

• $stream: El puntero de archivo que se va a vaciar. Debe ser un recurso de flujo válido y con permiso de escritura — típicamente uno devuelto por fopen(). Los flujos abiertos en modo solo lectura ('r') no tienen nada que vaciar.

Valor de retorno

fflush() devuelve true en caso de éxito o false en caso de error. Falla cuando el recurso no es un flujo abierto válido o cuando la escritura subyacente no puede completarse; en ese caso puede emitirse una advertencia. Dado que los fallos son poco frecuentes pero reales (disco lleno, tubería rota), verifica el valor de retorno cuando no puedes permitirte perder la escritura:

<?php

if (fflush($stream) === false) {
    // The buffered data could not be written — handle it (log, retry, abort).
}

Ejemplos

Ejemplo 1: Vaciar un puntero de archivo

Abre un archivo, escribe datos y luego vacía el búfer para que los bytes lleguen al flujo antes de que el script continúe:

Vaciar un puntero de archivo en PHP

<?php

$fileHandle = fopen('example.txt', 'w');
fwrite($fileHandle, 'Hello, World!');

if (fflush($fileHandle)) {
    echo "Buffer flushed to the stream.\n";
}

fclose($fileHandle);

Salida:

Buffer flushed to the stream.

Ejemplo 2: Un log vaciado de forma continua

Un proceso que añade entradas a un archivo de log y vacía el búfer después de cada una, de modo que otro proceso pueda usar tail -f sobre el archivo y ver las líneas en tiempo real en lugar de en ráfagas:

Registro en tiempo real con fflush()

<?php

$log = fopen('worker.log', 'a');

foreach (['started', 'processing', 'done'] as $event) {
    fwrite($log, date('c') . " {$event}\n");
    fflush($log); // each line is visible immediately, not only at fclose()
}

fclose($log);

Sin la llamada a fflush(), las tres líneas normalmente solo aparecerían cuando el búfer se llenara o cuando fclose() se ejecutara al final.

fflush() vs. fclose()

No necesitas usar fflush() justo antes de fclose() — fclose() vacía automáticamente cualquier dato en búfer antes de cerrar el recurso. Usa fflush() solo cuando necesites que los datos se escriban mientras el archivo sigue abierto.

fflush() no garantiza que los datos estén en disco

Este es el malentendido más frecuente. fflush() transfiere el búfer de PHP al sistema operativo, pero el sistema operativo mantiene su propia caché de escritura. Después de fflush(), los bytes pueden seguir estando en la caché del sistema operativo en lugar de en el disco físico. Si la máquina pierde energía justo después, los datos pueden perderse.

Para forzar al sistema operativo a confirmar los datos en almacenamiento duradero, continúa con fsync() (PHP 8.1+):

<?php

$file = fopen('important.txt', 'w');
fwrite($file, 'critical data');
fflush($file); // PHP buffer -> OS
fsync($file);  // OS cache -> physical disk (PHP 8.1+)
fclose($file);

Control del búfer en sí

Si quieres cambiar cuánto almacena PHP en el búfer antes de escribir automáticamente — en lugar de vaciarlo a demanda — usa set_file_buffer(). Establecer el tamaño del búfer en 0 desactiva el almacenamiento en búfer por completo, de modo que cada llamada a fwrite() se escribe directamente sin necesidad de un fflush() explícito.

Nota sobre el almacenamiento en búfer de salida

No confundas fflush() con las funciones de almacenamiento en búfer de salida de PHP como ob_flush() y flush(). fflush() opera sobre un recurso de archivo/flujo (archivos, sockets, tuberías). ob_flush() vacía el búfer de salida interno de PHP (el cuerpo de la página) hacia el servidor web o el cliente. Son mecanismos distintos que casualmente comparten la palabra "flush".

Conclusión

En conclusión, la función fflush() es una función PHP útil que garantiza que los datos en búfer se escriban de inmediato en un flujo de archivo. Es esencial para aplicaciones que requieren persistencia de datos en tiempo real, como sistemas de registro o scripts de procesamiento de datos.

Con los ejemplos proporcionados en este artículo, ahora deberías ser capaz de usar la función fflush() en tu código PHP con facilidad. Si tienes alguna pregunta o duda sobre el uso de la función fflush() en PHP, no dudes en contactarnos. Estaremos encantados de ayudarte.

Práctica