Función flush() de PHP: Enviar la salida al navegador de inmediato

De forma predeterminada, PHP recopila el texto que tu script imprime (con echo, print, etc.) y lo envía al navegador en bloques, normalmente solo cuando el script termina. La función integrada flush() te permite enviar inmediatamente lo que ya se ha producido en este momento, para que el usuario vea la salida parcial antes de que la página esté completamente generada. Esta página explica qué hace flush(), cómo difiere de ob_flush(), los búferes que se sitúan entre tu script y el navegador, y cuándo realmente conviene usarla.

Qué hace la función flush()

flush(): void

flush() le pide a PHP que entregue cualquier salida que esté reteniendo a la capa inferior: el SAPI y el servidor web. No recibe argumentos ni devuelve nada. Un uso habitual es un script de larga duración que debe mostrar progreso (una línea de registro, un contador) en lugar de dejar al usuario mirando una página en blanco hasta que todo termine.

Dos límites importantes:

• flush() no afecta a la propia capa de almacenamiento en búfer de salida de PHP (la iniciada con ob_start()). Si el almacenamiento en búfer de salida está activo, el texto sigue atrapado en el búfer de PHP y flush() no tiene nada que enviar. Primero debes liberar esa capa con ob_flush() o ob_end_flush().
• flush() no puede anular el almacenamiento en búfer realizado por el servidor web o proxy (Apache mod_deflate, Nginx proxy_buffering, FastCGI, gzip). Estos pueden seguir reteniendo los datos hasta que decidan enviarlos.

Un ejemplo básico

Cuando no hay almacenamiento en búfer de salida de PHP activo, flush() por sí solo es suficiente para enviar la salida actual:

<?php
echo "Starting a slow task...\n";
flush();        // send the line above to the browser now

sleep(2);       // pretend we are doing real work

echo "Done!\n";
?>

Sin la llamada a flush(), el usuario normalmente vería ambas líneas aparecer juntas después de 2 segundos. Con ella, "Starting a slow task..." puede llegar de inmediato.

flush() vs ob_flush()

Esta es la distinción que suele confundir a la gente. PHP puede apilar dos búferes separados, y cada función *flush apunta a uno diferente:

Cuando el almacenamiento en búfer de salida está activo, necesitas ambas, en orden: primero ob_flush() para liberar el búfer de PHP y luego flush() para enviarlo:

<?php
ob_start();             // turn on PHP output buffering
echo "Buffered text\n";

ob_flush();             // PHP buffer -> SAPI buffer
flush();                // SAPI buffer -> browser
?>

Si inviertes el orden u omites ob_flush(), el texto permanece atrapado dentro de PHP. Si deseas que PHP vacíe automáticamente tras cada echo, consulta ob_implicit_flush().

Por qué a menudo "no funciona"

Transmitir la salida de forma fiable es más difícil que llamar a una sola función, porque varias capas almacenan en búfer de forma independiente:

• gzip / compresión — zlib.output_compression y mod_deflate de Apache deben acumular suficientes bytes antes de enviar. Deshabilita la compresión para la respuesta que deseas transmitir.
• Almacenamiento en búfer del servidor web / proxy — Nginx (proxy_buffering on), FastCGI y los balanceadores de carga suelen volver a almacenar en búfer la respuesta.
• Renderizado del navegador — algunos navegadores esperan un número mínimo de bytes antes de pintar; rellenar la salida puede forzar un pintado más temprano.

Debido a esto, flush() es mejor tratarla como una sugerencia, no como una garantía. Para necesidades de transmisión modernas (eventos enviados por el servidor, APIs en fragmentos), configura el servidor explícitamente en lugar de depender únicamente de flush().

Funciones de salida relacionadas

• ob_flush() — vacía el búfer de control de salida de PHP.
• ob_end_flush() — vacía y desactiva el almacenamiento en búfer de salida.
• ob_get_flush() — devuelve el contenido del búfer y lo vacía.
• PHP Output Control — descripción general de cómo encajan las capas de almacenamiento en búfer.
• fflush() — vacía las escrituras en búfer en un archivo abierto (no en el navegador).

Conclusión

flush() fuerza a PHP a enviar la salida que ya ha producido hacia el navegador en lugar de esperar a que el script termine. Recuerda que solo afecta al búfer SAPI/escritura: con ob_start() activo debes llamar primero a ob_flush() y, aun así, el servidor web o la capa de compresión pueden retrasar la entrega. Usada con esa comprensión, flush() es una forma práctica de transmitir el progreso de scripts de larga duración.

Práctica