When working with PHP in PHP, it helps to understand exactly what readfile() does and when the result is useful. This guide uses small examples followed by a practical pattern.
What Is readfile() in PHP?
Streams a file directly to output and returns the byte count, or false on failure. It does not return the file contents as a string.
Syntax:
readfile(string $filename, bool $use_include_path = ..., $context = ...) : int|false
Parameters:
$filename(string) is required.$use_include_path(bool) is optional.$contextis optional.
Return value: PHP declares int|false for this API in PHP 8.4 where available. For operations that can fail, check errors or exceptions instead of assuming success.
Example 1: Basic Usage
The first example focuses on the operation itself without unrelated application logic.
<?php
$filePath = __DIR__ . "/manual.txt";
$gzipPath = __DIR__ . "/manual.txt.gz";
if (!is_file($filePath)) {
throw new RuntimeException("Example file not found");
}
readfile($filePath);
Streams a file directly to output and returns the byte count, or false on failure. It does not return the file contents as a string. The example demonstrates the API in an isolated teaching script. File paths, permissions and optional extensions may need adapting for a real project.
Example 2: Handling Conditions and Failures
Production code must handle cases where the archive, file, runtime feature, or source path is not available. The following example demonstrates an additional usage pattern.
<?php
$downloadPath = __DIR__ . "/export.csv";
if (!is_file($downloadPath)) {
throw new RuntimeException("Missing download file");
}
$bytesSent = readfile($downloadPath);
if ($bytesSent === false) {
throw new RuntimeException("Streaming failed");
}
Only catch errors you can handle meaningfully. A PHP warning, a false return value, and an exception are not interchangeable; consult the behavior explained above.
Practical Example: Integrating the Operation
This practical variation shows how to place the operation in a larger file or inspection workflow. The paths and names are illustrative rather than server deployment instructions.
<?php
function inspectEnvironment(): void
{
readfile($filePath);
}
inspectEnvironment();
Do not copy sample paths blindly into production. Validate allowed paths and confirm the appropriate extension and filesystem permissions first.
Important Behavior and Edge Cases
- The function writes file contents to the output stream, so it must not be used on private server-side data.
- Set the correct Content-Type and Content-Disposition before streaming HTTP downloads.
- Untrusted path input must be checked against an allowed directory.
Comparison With Related Functions
| Function or Method | Purpose |
|---|---|
readfile | Streams a file directly to output and returns the byte count, or false on failure. It does not return the file contents as a string. |
file_get_contents() | Loads file contents into a string instead of directly streaming them. |
realpath() | Resolves a filesystem path instead of inspecting or changing a PHP setting. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Assuming filesystem state cannot change after a check. | Handle failures from the actual file operation. |
| Passing unchecked user paths into filesystem APIs. | Restrict paths to known directories and validate resolved destinations. |
| Displaying sensitive filesystem configuration to visitors. | Keep diagnostic output in restricted administrative tools. |
Key Takeaways
- Streams a file directly to output and returns the byte count, or false on failure. It does not return the file contents as a string.
- The function writes file contents to the output stream, so it must not be used on private server-side data.
- Set the correct Content-Type and Content-Disposition before streaming HTTP downloads.
readfile() is useful when its specific purpose matches your application. Keep the examples focused, respect the restrictions above, and validate real-world inputs rather than relying on the example values.