fpassthru()

What is the fpassthru() Function?

The fpassthru() function is a built-in PHP function that reads all remaining data from an open file pointer — starting at the current pointer position and continuing to the end of the file (EOF) — and writes it directly to the output stream (what the browser or the terminal receives). Because it streams the data in chunks instead of loading the whole file into a string, it is well suited to sending large files without exhausting PHP's memory limit.

This page covers the function's syntax, a step-by-step usage pattern, a real-world file-download example, how it differs from readfile(), and the gotchas worth knowing.

It returns the number of bytes written to the output on success, or false on failure.

Here's the basic syntax of the fpassthru() function:

The PHP syntax of fpassthru()

fpassthru(resource $stream): int|false

Where $stream is a file pointer that must be valid and already open (typically the return value of fopen()). After fpassthru() returns, the pointer is at EOF and the data has been consumed — you cannot read it again without rewinding.

How to Use the fpassthru() Function?

Using the fpassthru() function is straightforward. Here are the steps to follow:

1. Open the file with fopen() and ensure the file pointer is at the desired starting position.
2. Call fpassthru() with the file pointer. It will read until EOF and write to the output stream.
3. Check the return value to confirm success, then close the file with fclose().

Here's an example code snippet that demonstrates how to use the fpassthru() function:

How to Use the fpassthru() Function?

<?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 this example, we open the file largefile.txt using the fopen() function in read-only mode. We check if the file was opened successfully using an if statement, and if it was, we output its contents to the standard output stream with fpassthru(). We verify the return value to handle potential read errors, then close the handle with fclose().

Note on output buffering: If PHP output buffering is active (e.g., via ob_start()), fpassthru() will write directly into the current output buffer instead of sending data immediately to the browser.

Reading From the Current Position, Not the Whole File

A key detail is that fpassthru() starts at the current pointer position. If you have already read part of the file (for example with fgets() or fread()), only the remaining bytes are sent. This lets you read a header yourself and stream the rest:

<?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);

This prints:

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

The HEADER line is not repeated, because the pointer had already advanced past it when fpassthru() ran.

Sending a File as a Download

The most common production use of fpassthru() is streaming a file to the browser as a download. Set the appropriate headers, open the file in binary mode ('rb'), and let fpassthru() push the bytes:

<?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.';

The 'rb' mode matters on Windows, where the default text mode would corrupt binary data such as images, PDFs, or archives. On Linux and macOS the b flag is harmless, so it is good practice to always include it for downloads.

fpassthru() vs. readfile()

Both functions stream a file to output, but they operate at different levels:

If you simply want to output an entire file and have no open handle, readfile() is shorter. Reach for fpassthru() when you already hold a file pointer or need to skip past a portion of the stream first.

Conclusion

The fpassthru() function is a useful tool in PHP for reading large files without loading them into memory. By following the steps outlined in this guide, you can easily use the fpassthru() function in your PHP projects to read the contents of files from the current pointer position and output them to the standard output stream.

Practice