fpassthru()

Was ist die Funktion fpassthru()?

Die Funktion fpassthru() ist eine eingebaute PHP-Funktion, die alle verbleibenden Daten eines geöffneten Dateizeigers liest — beginnend an der aktuellen Zeigerposition bis zum Dateiende (EOF) — und sie direkt in den Ausgabestream schreibt (was der Browser oder das Terminal empfängt). Da die Daten in Blöcken übertragen werden, anstatt die gesamte Datei in einen string zu laden, eignet sich die Funktion besonders gut zum Senden großer Dateien, ohne PHPs Speicherlimit zu erschöpfen.

Diese Seite behandelt die Syntax der Funktion, ein schrittweises Verwendungsmuster, ein praxisnahes Beispiel zum Herunterladen von Dateien, die Unterschiede zu readfile() sowie wichtige Fallstricke.

Bei Erfolg gibt die Funktion die Anzahl der in die Ausgabe geschriebenen Bytes zurück, bei einem Fehler false.

Hier ist die grundlegende Syntax der Funktion fpassthru():

Die PHP-Syntax von fpassthru()

fpassthru(resource $stream): int|false

Dabei ist $stream ein Dateizeiger, der gültig und bereits geöffnet sein muss (in der Regel der Rückgabewert von fopen()). Nachdem fpassthru() zurückgekehrt ist, befindet sich der Zeiger am EOF und die Daten wurden verbraucht — ohne Zurückspulen können sie nicht erneut gelesen werden.

Wie verwendet man die Funktion fpassthru()?

Die Verwendung der Funktion fpassthru() ist unkompliziert. Hier sind die Schritte, die zu befolgen sind:

1. Öffnen Sie die Datei mit fopen() und stellen Sie sicher, dass der Dateizeiger an der gewünschten Startposition steht.
2. Rufen Sie fpassthru() mit dem Dateizeiger auf. Die Funktion liest bis zum EOF und schreibt in den Ausgabestream.
3. Überprüfen Sie den Rückgabewert, um den Erfolg zu bestätigen, und schließen Sie die Datei anschließend mit fclose().

Hier ist ein Codebeispiel, das zeigt, wie die Funktion fpassthru() verwendet wird:

Verwendung der Funktion fpassthru()

<?php

$filename = 'largefile.txt';
$file = fopen($filename, 'r');
if ($file) {
   if (fpassthru($file) === false) {
      echo "Error reading file!";
   }
   fclose($file);
} else {
   echo "Unable to open file!";
}

In diesem Beispiel öffnen wir die Datei largefile.txt mit der Funktion fopen() im schreibgeschützten Modus. Mit einer if-Anweisung prüfen wir, ob die Datei erfolgreich geöffnet wurde. Falls ja, geben wir ihren Inhalt mit fpassthru() in den Standardausgabestream aus. Wir überprüfen den Rückgabewert, um potenzielle Lesefehler zu behandeln, und schließen dann das Handle mit fclose().

Hinweis zur Ausgabepufferung: Wenn die PHP-Ausgabepufferung aktiv ist (z. B. über ob_start()), schreibt fpassthru() direkt in den aktuellen Ausgabepuffer, anstatt die Daten sofort an den Browser zu senden.

Lesen ab der aktuellen Position, nicht der gesamten Datei

Ein wichtiges Detail ist, dass fpassthru() an der aktuellen Zeigerposition beginnt. Wenn Sie bereits einen Teil der Datei gelesen haben (z. B. mit fgets() oder fread()), werden nur die verbleibenden Bytes gesendet. Damit können Sie einen Header selbst lesen und den Rest streamen:

<?php

$file = fopen('php://temp', 'r+');
fwrite($file, "HEADER\nbody-line-1\nbody-line-2\n");
rewind($file);

// Consume the first line manually.
echo "First line: " . fgets($file);

// Stream everything left after the pointer.
fpassthru($file);
fclose($file);

Die Ausgabe lautet:

First line: HEADER
body-line-1
body-line-2

Die Zeile HEADER wird nicht wiederholt, da der Zeiger bereits daran vorbeigegangen war, als fpassthru() ausgeführt wurde.

Eine Datei als Download senden

Die häufigste Verwendung von fpassthru() in der Produktion ist das Streamen einer Datei an den Browser als Download. Setzen Sie die entsprechenden Header, öffnen Sie die Datei im Binärmodus ('rb'), und lassen Sie fpassthru() die Bytes übertragen:

<?php

$path = '/var/www/files/report.pdf';

if (is_readable($path)) {
   header('Content-Type: application/pdf');
   header('Content-Disposition: attachment; filename="report.pdf"');
   header('Content-Length: ' . filesize($path));

   $file = fopen($path, 'rb');
   fpassthru($file);
   fclose($file);
   exit;
}

http_response_code(404);
echo 'File not found.';

Der Modus 'rb' ist unter Windows wichtig, wo der standardmäßige Textmodus Binärdaten wie Bilder, PDFs oder Archive beschädigen würde. Unter Linux und macOS ist das Flag b harmlos, daher empfiehlt es sich, es bei Downloads stets anzugeben.

fpassthru() vs. readfile()

Beide Funktionen streamen eine Datei in die Ausgabe, arbeiten jedoch auf unterschiedlichen Ebenen:

Wenn Sie einfach eine ganze Datei ausgeben und kein offenes Handle haben, ist readfile() kürzer. Verwenden Sie fpassthru(), wenn Sie bereits einen Dateizeiger haben oder zunächst einen Teil des Streams überspringen müssen.

Fazit

Die Funktion fpassthru() ist ein nützliches Werkzeug in PHP, um große Dateien zu lesen, ohne sie in den Speicher zu laden. Wenn Sie die in diesem Leitfaden beschriebenen Schritte befolgen, können Sie die Funktion fpassthru() problemlos in Ihren PHP-Projekten einsetzen, um den Inhalt von Dateien ab der aktuellen Zeigerposition zu lesen und in den Standardausgabestream auszugeben.

Übungen