fflush()

Einführung in die PHP-Funktion fflush()

Die Funktion fflush() in PHP zwingt alle Daten, die sich noch im Schreibpuffer eines Dateizeigers befinden, sofort in den zugrundeliegenden Stream zu schreiben, anstatt darauf zu warten, dass der Puffer gefüllt wird oder der Stream geschlossen wird.

Wenn Sie fwrite() aufrufen, schreibt PHP die Bytes nicht zwingend direkt auf die Festplatte. Aus Leistungsgründen werden die Daten in einem In-Memory-Puffer gesammelt und in größeren Blöcken geschrieben. Das ist normalerweise das gewünschte Verhalten — manchmal müssen die Daten jedoch sofort ankommen: bei einer per tail verfolgbaren Log-Datei, einem langlaufenden Worker-Prozess, den ein anderer Prozess liest, oder einem Skript, das vor dem Abschluss beendet werden könnte. fflush() ist die Funktion, die sagt: „Warte nicht, schreibe was du hast."

Diese Seite behandelt die Syntax, Parameter, den Rückgabewert und mehrere ausführbare Beispiele sowie häufige Fallstricke — einschließlich des entscheidenden Unterschieds zwischen fflush() und der Synchronisierung auf Betriebssystemebene.

Syntax

Die Syntax der Funktion fflush() lautet wie folgt:

Die PHP-Syntax von fflush()

bool fflush ( resource $stream )

• stream: der Dateizeiger, der geleert werden soll

Parameter

Die Funktion fflush() nimmt einen erforderlichen Parameter entgegen:

• $stream: Der zu leerende Dateizeiger. Es muss eine gültige, beschreibbare Stream-Ressource sein — typischerweise eine, die von fopen() zurückgegeben wird. Streams, die nur lesend geöffnet wurden (Modus 'r'), haben nichts zu leeren.

Rückgabewert

fflush() gibt true bei Erfolg oder false bei Fehler zurück. Es schlägt fehl, wenn die Ressource kein gültiger offener Stream ist oder der zugrundeliegende Schreibvorgang nicht abgeschlossen werden kann; dabei kann eine Warnung ausgegeben werden. Da Fehler zwar selten, aber real sind (eine volle Festplatte, eine unterbrochene Pipe), sollte der Rückgabewert geprüft werden, wenn der Schreibvorgang nicht verloren gehen darf:

<?php

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

Beispiele

Beispiel 1: Einen Dateizeiger leeren

Öffnen Sie eine Datei, schreiben Sie Daten und leeren Sie dann den Puffer, damit die Bytes den Stream erreichen, bevor das Skript fortfährt:

Einen Dateizeiger in PHP leeren

<?php

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

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

fclose($fileHandle);

Ausgabe:

Buffer flushed to the stream.

Beispiel 2: Ein kontinuierlich geleertes Log

Ein Worker, der Einträge an eine Log-Datei anhängt und nach jedem Eintrag den Puffer leert, sodass ein anderer Prozess die Datei per tail -f verfolgen und Zeilen in Echtzeit sehen kann, anstatt sie in Blöcken zu erhalten:

Echtzeit-Logging mit 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);

Ohne den fflush()-Aufruf würden die drei Zeilen normalerweise erst erscheinen, wenn der Puffer voll ist oder wenn fclose() am Ende ausgeführt wird.

fflush() vs. fclose()

Sie brauchen fflush() nicht unmittelbar vor fclose() — fclose() leert alle verbleibenden gepufferten Daten automatisch, bevor die Ressource geschlossen wird. Verwenden Sie fflush() nur dann, wenn die Daten geschrieben werden müssen, während die Datei noch geöffnet ist.

fflush() garantiert nicht, dass die Daten auf der Festplatte sind

Dies ist das häufigste Missverständnis. fflush() übergibt PHP's Puffer an das Betriebssystem, aber das Betriebssystem unterhält seinen eigenen Schreib-Cache. Nach fflush() können sich die Bytes noch im OS-Cache befinden und nicht auf dem physischen Datenträger. Wenn der Rechner unmittelbar danach den Strom verliert, können die Daten verloren gehen.

Um das Betriebssystem zu zwingen, die Daten dauerhaft zu speichern, verwenden Sie anschließend 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);

Den Puffer selbst steuern

Wenn Sie ändern möchten, wie viel PHP puffert, bevor es automatisch schreibt — anstatt den Puffer auf Abruf zu leeren — verwenden Sie set_file_buffer(). Wenn die Puffergröße auf 0 gesetzt wird, wird die Pufferung vollständig deaktiviert, sodass jeder fwrite()-Aufruf direkt durchgeschrieben wird, ohne ein explizites fflush() zu benötigen.

Hinweis zur Ausgabepufferung

Verwechseln Sie fflush() nicht mit PHP's Ausgabepuffer-Funktionen wie ob_flush() und flush(). fflush() arbeitet auf einer Datei-/Stream-Ressource (Dateien, Sockets, Pipes). ob_flush() leert PHP's internen Ausgabepuffer (den Seiteninhalt) in Richtung des Webservers oder Clients. Es handelt sich um unabhängige Mechanismen, die zufällig das Wort „flush" gemeinsam haben.

Fazit

Zusammenfassend lässt sich sagen, dass die Funktion fflush() eine nützliche PHP-Funktion ist, die sicherstellt, dass gepufferte Daten sofort in einen Datei-Stream geschrieben werden. Sie ist unverzichtbar für Anwendungen, die eine Echtzeit-Datenpersistenz erfordern, wie z. B. Logging-Systeme oder Datenverarbeitungsskripte.

Anhand der in diesem Artikel bereitgestellten Beispiele sollten Sie die Funktion fflush() nun problemlos in Ihrem PHP-Code verwenden können. Wenn Sie Fragen oder Bedenken zur Verwendung der Funktion fflush() in PHP haben, wenden Sie sich gerne an uns. Wir helfen Ihnen gerne weiter.

Übung