【PHP8.x】fflush関数の使い方

fflush関数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年09月30日

基本的な使い方

fflush関数は、指定されたファイルポインタに関連付けられた出力バッファの内容を、強制的に物理的な出力デバイス（ファイルや標準出力など）へ書き出す（フラッシュする）関数です。

PHPでファイルへの書き込み処理を行う際、システムの効率を高めるために、書き込むデータは一度「バッファ」と呼ばれるメモリ上の仮置き場に一時的に溜められます。このバッファがいっぱいになるか、ファイルを閉じるなどの特定のタイミングで、実際にファイルや画面へデータが書き込まれます。

fflush関数を使用すると、このバッファに溜まっているデータを、上記のタイミングを待たずに、すぐに強制的に出力先へ書き出すことができます。例えば、ログファイルをリアルタイムで更新し、常に最新の情報を確認したい場合や、プログラムが何らかの理由で予期せず終了する可能性がある前に、重要なデータを確実にディスクに保存しておきたい場合などに非常に有効です。また、ネットワーク通信やパイプを使ったプロセス間通信で、送信データをすぐに相手に届けたいときにも利用されます。

この関数は、書き込みをフラッシュしたいファイルポインタ（fopen関数などで取得したもの）を引数として受け取ります。処理が成功した場合は true を、失敗した場合は false を返します。特にWindows環境では、オペレーティングシステムによるバッファリングの影響で、fflushを呼び出してもデータが必ずしも即座に物理ディスクに書き込まれるわけではない点にご注意ください。

構文(syntax)


1fflush(resource $stream): bool

引数(parameters)

resource $stream

resource $stream: 出力バッファをフラッシュする対象となるファイルリソースまたはストリームを指定します。

戻り値(return)

bool

指定されたバッファの内容をファイルにフラッシュし、その操作が成功したかどうかを真偽値で返します。成功した場合は true、失敗した場合は false を返します。

サンプルコード

PHP fflush(STDOUT)による標準出力バッファのフラッシュ


1<?php
2
3// 標準出力に文字列を書き込む
4// fwrite()関数は、指定されたファイルポインタにデータを書き込みます。
5// STDOUTはPHPの定数で、標準出力のファイルポインタを表します。
6fwrite(STDOUT, "このメッセージは、システムのバッファに一時的に保持される可能性があります。\n");
7
8// 標準出力のバッファを強制的にフラッシュする
9// fflush()関数は、指定されたファイルポインタ（この場合は標準出力）の出力バッファにあるデータを、
10// 実際の出力先（通常はコンソール）に強制的に書き出します。
11// これにより、出力が遅延することなく即座に表示されます。
12if (fflush(STDOUT)) {
13    // フラッシュが成功した場合
14    fwrite(STDOUT, "標準出力バッファが正常にフラッシュされました。\n");
15} else {
16    // フラッシュが失敗した場合（システムI/Oに関する問題など、稀に発生）
17    error_log("エラー: 標準出力バッファのフラッシュに失敗しました。\n");
18    fwrite(STDOUT, "エラー: 標準出力バッファのフラッシュに失敗しました。\n");
19}
20
21// フラッシュ後、さらにメッセージを書き込む
22fwrite(STDOUT, "これはフラッシュ後に表示されるメッセージです。\n");
23
24?>

上記のサンプルコードは、PHPのfflush関数がどのように出力バッファを制御するかを示しています。プログラムが出力を行う際、メッセージは通常、すぐに画面に表示されるわけではなく、「バッファ」と呼ばれる一時的な記憶場所に溜められます。

まず最初のfwrite(STDOUT, ...)は、STDOUT（標準出力、通常はコンソール画面）に対してメッセージを書き込んでいます。この時点では、メッセージはまだバッファにあり、すぐには表示されない可能性があります。

次に登場するfflush(STDOUT)がこのバッファの挙動を制御します。fflush関数は、引数resource $streamで指定された出力先（この場合はSTDOUT）のバッファに溜まっているすべてのデータを、強制的に実際の出力先へ書き出します。これにより、メッセージは遅延することなく即座に画面に表示されるようになります。fflush関数の戻り値はbool型で、バッファのフラッシュが成功した場合はtrueを、失敗した場合はfalseを返します。

サンプルコードでは、if (fflush(STDOUT))でフラッシュの成否を確認しています。成功した場合は「標準出力バッファが正常にフラッシュされました。」と表示し、万が一失敗した場合はエラーメッセージを出力します。フラッシュの失敗は稀ですが、システムのI/Oに関する問題などが原因で発生する可能性があります。

最後のfwriteは、フラッシュが完了した後に表示されるメッセージです。これにより、前のメッセージがfflushによって確実に表示された後に、このメッセージが続くことが確認できます。このようにfflushを使うことで、プログラムの出力を意図したタイミングで確実に表示させることが可能になります。

fflush関数は、fwriteなどで書き込んだデータがシステムのバッファに一時的に保持され、すぐに表示されない場合があるのを防ぎ、強制的に出力させるために使われます。特に、プログラムの実行中にデバッグ情報や進行状況をリアルタイムで確認したい場合に非常に役立ちます。しかし、通常の出力では不要な場面も多く、頻繁な呼び出しは処理性能に影響を与える可能性があるため、必要な場合にのみ使用することが重要です。また、fflushは成功・失敗をブール値で返すため、必ず戻り値を確認し、失敗時にはエラーログの出力など、適切なエラー処理を行うことで、より安全なコードになります。