HTTP Headers for File Downloads

HTTP Headers for File Downloads

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

HTTP Headers for File Downloads

When a PHP script serves a file, the primary goal is to signal to the browser that this response should be treated as a downloadable artifact rather than content to be rendered inline. The source material correctly identifies that setting Content-Disposition: attachment is the critical step to trigger the download dialog. However, relying on this header alone is insufficient for robust behavior across different browsers and operating systems.

The specific issue of files being misidentified—such as a binary executable being displayed as a GIF—is almost certainly caused by an incorrect or missing MIME type in the Content-Type header. Without a valid MIME type, many browsers attempt to guess the file format based solely on the file extension. If your script strips the original filename or if the extension does not match the actual content (e.g., renaming a PDF to .gif), and you provide no Content-Type, the browser defaults to application/octet-stream or tries to render it as an image if the header is entirely absent, leading to the rendering anomalies users are experiencing.

The provided implementation attempts to map file extensions to MIME types using a static array. While this approach covers common formats like PDFs and images, it has inherent limitations. It fails for binary data without extensions, modern container formats like .tar.gz or .zip (which might need specific handling depending on the OS), and non-standard media files. Furthermore, the fallback to application/force-download is not a standard MIME type; while some browsers respect it to trigger a download, others may ignore it entirely if the extension suggests an image or video format. A more reliable generic fallback for unknown binary files is often application/octet-stream, which explicitly tells the browser "do not render this."

Handling Output Buffering and Compression

A significant performance bottleneck mentioned in the source material is the delay between script execution and the appearance of the download dialog. The code includes logic to disable zlib output compression via ini_set('zlib.output_compression', 'Off'). This is a necessary step, but it addresses only half of the equation.

PHP's default behavior often enables output buffering (output_buffering), which stores data in memory before sending it to the client. When combined with ob_end_clean(), this can sometimes cause issues if headers are sent too late or if the buffer state is inconsistent. More importantly, modern browsers expect a specific sequence: headers must be sent immediately, followed by the body. If the server waits until the end of the script execution to flush the output, the browser might delay rendering the download prompt until the entire response is received and validated against its cache expectations.

The implementation also disables zlib.output_compression. This is correct because zlib-compressed output interferes with Range Requests (download resuming). If a user downloads 50% of a file and reconnects, the server needs to send the remaining bytes uncompressed so the client can verify integrity and append them correctly. Enabling compression here would break the resume functionality entirely.

Implementing Range Requests for Large Files

The code snippet implements support for HTTP_RANGE headers, which allows clients to resume interrupted downloads or load files partially. This is a best practice for large files to improve perceived performance. The logic parses the range string to calculate the new file length and updates the Content-Range header accordingly.

However, there is a subtle bug in the provided Content-Range calculation:

header('Content-Range: bytes ' . $range - $rangeEnd / $fileSize);

This line performs arithmetic on the string values before converting them to integers (due to operator precedence and type juggling), resulting in an invalid header value. The correct calculation should ensure integer division is applied explicitly, or simply output the absolute byte range:

header('Content-Range: bytes ' . $range . '-' . $rangeEnd . '/'. $fileSize);

An incorrect Content-Range header can cause browsers to fail to resume downloads properly, treating the partial response as invalid.

Final Header Considerations

The headers Cache-Control: private, Pragma: private, and Expires are correctly set to prevent the browser from caching the file locally. This ensures that every download request is fresh and prevents users from seeing stale versions of files after updates. However, for sensitive downloads or very large files, consider adding X-Accel-Redirect in a proxy setup (like Nginx) if you are serving static files from disk rather than streaming them directly from PHP, though the current implementation handles direct streaming well.

In summary, to fix the identification issues, ensure that every file response includes a definitive Content-Type. Use a robust mapping for known extensions and default to application/octet-stream for unknown binary content. To resolve the delay issue, verify that output buffering is fully disabled (output_buffering = Off in php.ini) alongside your runtime configuration changes, ensuring headers are sent immediately upon script start without waiting for buffer flushes.

Our network