Signatur
Beschreibung
fpassthru() liest den gesamten Inhalt eines Datei-Handles ab der aktuellen Position des Dateizeigers und schreibt ihn direkt in den Ausgabe-Puffer (Standard-Output). Die Funktion ist besonders nützlich, wenn eine bereits geöffnete Datei oder ein Stream vollständig an den Browser bzw. Client gesendet werden soll, ohne sie erst in den PHP-Speicher zu laden.
Ein typischer Anwendungsfall ist der Download-Controller: Nach dem Setzen passender HTTP-Header (z. B. Content-Type, Content-Disposition) kann fpassthru() die Binärdaten einer Datei effizient an den Client übertragen. Da die Funktion intern streamt, ist der Speicherverbrauch gering – auch bei großen Dateien.
Vor dem Aufruf von fpassthru() können Sie den Dateizeiger mithilfe von rewind() oder fseek() an eine bestimmte Position setzen, um nur einen Teil der Datei auszugeben. Die Funktion schließt das Datei-Handle nicht automatisch; das muss der Entwickler selbst mit fclose() erledigen.
Alternativ steht für noch nicht geöffnete Dateien die Funktion readfile() zur Verfügung, die Öffnen, Ausgeben und Schließen in einem Schritt erledigt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handle Pflicht | resource | Ein gültiges Datei-Handle, das z. B. von fopen() zurückgegeben wurde. Der Zeiger bestimmt, ab welcher Stelle die Ausgabe beginnt. |
Rückgabewert
int zurück. Im Fehlerfall wird false zurückgegeben.Beispiele
Datei-Download mit fpassthru()
<?php
$datei = '/var/www/downloads/bericht.pdf';
if (!file_exists($datei)) {
http_response_code(404);
exit('Datei nicht gefunden.');
}
$handle = fopen($datei, 'rb');
if ($handle === false) {
http_response_code(500);
exit('Datei konnte nicht geöffnet werden.');
}
header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="bericht.pdf"');
header('Content-Length: ' . filesize($datei));
// Ausgabe-Puffer leeren, um unerwünschte Vorab-Ausgaben zu vermeiden
ob_clean();
flush();
$bytes = fpassthru($handle);
fclose($handle);
// $bytes enthält die Anzahl der gesendeten Bytes
// z. B.: 204800Nur den zweiten Teil einer Datei ausgeben
<?php
$handle = fopen('logfile.txt', 'rb');
if ($handle === false) {
exit('Fehler beim Öffnen.');
}
// Dateizeiger auf Byte 1024 setzen
fseek($handle, 1024);
// Alle Daten ab Position 1024 ausgeben
$bytes = fpassthru($handle);
fclose($handle);
echo PHP_EOL . "Ausgegebene Bytes: " . $bytes;// Wichtig · Fallstricke
Sicherheit: Stellen Sie sicher, dass der Dateipfad nicht durch Benutzereingaben manipuliert werden kann (Path-Traversal-Angriffe). Validieren und normalisieren Sie Pfade stets mit realpath() und prüfen Sie, ob die aufgelöste Datei sich innerhalb des erlaubten Verzeichnisses befindet.
Binärmodus: Öffnen Sie Dateien (insbesondere auf Windows-Systemen) im Binärmodus ('rb'), um Zeilenumbruch-Konvertierungen zu vermeiden, die bei Binärdateien zu Korruptionen führen können.
Ausgabe-Puffer: Falls PHP-Output-Buffering aktiv ist, kann die Ausgabe im Puffer gehalten werden, bevor sie an den Client gesendet wird. Verwenden Sie ob_clean() und flush() vor dem Aufruf, um sicherzustellen, dass keine unerwünschten Zeichen (z. B. BOM oder Leerzeichen) vorangestellt werden.
Speicher: fpassthru() liest die Daten intern in Chunks, ohne die gesamte Datei in den PHP-Arbeitsspeicher zu laden – im Gegensatz zu file_get_contents() gefolgt von echo.