flush
Flushes PHP's system write buffers and the backing web server buffer so output reaches the client now.
flush(): void- Added in PHP 4.0
Return value
voidNo value is returned.
Changelog
- PHP 8.4.0Flushing headers without a body now succeeds under FastCGI.
Output in PHP passes through two independent layers. The upper layer is the userland buffer stack created by ob_start(); the lower layer is the buffer belonging to the SAPI and the web server (CGI, FastCGI, mod_php, or the CLI's stdout). flush() pushes the lower layer only.
When to reach for it
Use it whenever a script produces output over time and the reader should see it as it happens: a long import printing progress lines, a Server-Sent Events endpoint, or a large CSV streamed row by row instead of assembled in memory.
What trips people up
Calling flush() while an ob_start() buffer is open does nothing visible, because the text is still sitting in the userland buffer. The working idiom is both calls in order:
ob_flush(); flush();
Even then the data can be held elsewhere. Web servers buffer their own output (nginx proxy_buffering, gzip and deflate modules, FastCGI response buffering), and browsers often wait for a kilobyte or so before rendering anything. None of that is under PHP's control.
In a web context flush() also sends the headers, so any header() call or header-writing handler such as ob_gzhandler() must run before it.
Example
When to use it
- Print live progress lines from a long-running CLI import instead of one silent block at the end.
- Stream a Server-Sent Events feed so the browser receives each event as it is generated.
- Send a large CSV export row by row to keep memory flat on multi-million-row exports.
Frequently asked questions
What is the difference between flush and ob_flush?
ob_flush() empties PHP's own output buffer created by ob_start(), while flush() empties the buffer belonging to the SAPI and web server. When an output buffer is open you need both, in that order.
Why does flush not work on my page?
Almost always because something downstream is still buffering: an open ob_start() buffer, gzip compression, nginx proxy_buffering, or the browser waiting for enough bytes to start rendering. flush() cannot override any of those.
Do I need flush in a CLI script?
Rarely. The CLI SAPI writes to stdout with very little buffering, so echo normally appears immediately; flush() is only useful there when output is piped into another program that buffers.
More examples
flush() alone cannot defeat ob_start()
Both lines appear only after ob_end_flush() runs. ob_get_length() reports 29, proving the text was still queued in the userland buffer at the moment flush() was called.
<?php
ob_start();
echo "still buffered\n";
flush(); // does not release the ob_start() buffer
echo "also buffered\n";
$len = ob_get_length();
ob_end_flush();
echo "the buffer held {$len} bytes before it was released\n";Chunked output with a size threshold
The four words print in order, and the counter shows 2: the buffer crossed 10 bytes after 'beta' and again after 'delta', so it was pushed out twice before the final ob_end_flush().
<?php
ob_start();
$flushes = 0;
foreach (['alpha', 'beta', 'gamma', 'delta'] as $word) {
echo $word, "\n";
if (ob_get_length() >= 10) {
ob_flush();
flush();
$flushes++;
}
}
ob_end_flush();
echo "released the buffer $flushes times mid-loop\n";
Discussion