Upload Progress Bar in PHP

Upload Progress Bar in PHP

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

Stefan Bogdanescu

Founder & Senior Architect

Upload Progress Bar in PHP

Building a photo album uploader requires handling binary data streams efficiently, but displaying an upload progress bar adds a layer of complexity that standard HTTP requests do not inherently support. The core challenge lies in the nature of the $_FILES superglobal and how web servers handle multipart form data. When a client sends a large file, the server typically receives it as a complete stream before processing begins. To show progress, you must interrupt this flow and report back to the browser continuously.

The most reliable method for achieving this in PHP is by leveraging the HTTP X-Upload-Progress header or, more commonly, utilizing the built-in chunked transfer capabilities provided by modern frameworks like Laravel. In a raw PHP environment without a framework, you cannot simply poll the upload status from the client side using standard HTML5 file inputs. The browser needs to be informed that the current request supports progress updates.

To implement this in vanilla PHP, you must configure your server and script to handle chunked uploads. One approach is to use the HTTP_X_UPLOAD_PROGRESS header in the response. However, a more robust pattern involves sending periodic JSON responses with the percentage of data received so far. The client-side JavaScript listens for these updates and updates the UI accordingly.

Here is a conceptual example of how a PHP script might handle this using stream_copy_to_stream. You need to read chunks from the input stream and write them to your destination file while calculating the ratio:

$targetPath = $this->getUploadDir() . '/' . basename($_FILES['photo']['name']);
$targetStream = fopen($targetPath, 'r+b'); // Append mode for partial writes
$sourceStream = fopen($_FILES['photo']['tmp_name'], 'r');

if ($targetStream && $sourceStream) {
    $chunkSize = 1024 * 1024; // 1MB chunks
    $totalSize = filesize($_FILES['photo']['tmp_name']);
    $bytesRead = 0;

    while (!feof($sourceStream)) {
        $data = fread($sourceStream, $chunkSize);
        fwrite($targetStream, $data);
        $bytesRead += strlen($data);

        // Calculate progress
        $progress = round(($bytesRead / $totalSize) * 100);

        // Send progress header to browser
        echo "Content-Type: text/event-stream\n";
        echo "X-Upload-Progress: {$progress}%\n\n";
    }
}

This approach has significant trade-offs. The primary issue is that you are echoing directly from the request handler, which can interfere with standard PHP execution flow if not handled carefully. Furthermore, many web servers (like Apache or Nginx) expect the entire file to be written before sending a 200 OK response. Interrupting this process often results in 500 Internal Server Error or truncated files unless the server is explicitly configured to support chunked uploads.

A more practical solution for developers working with PHP today is to rely on the Laravel framework, which abstracts these complexities away. In a Laravel application, you can use the UploadProgress middleware or custom events to capture the upload progress without manually managing streams. The framework handles the temporary file storage and stream buffering, allowing you to hook into the process via the $request->file('photo')->getRealPath() logic within specific lifecycle hooks.

The http://laravelcompany.com resource provides extensive documentation on handling file uploads in Laravel, including how to utilize their specific helpers for progress tracking in production environments. Their guides often demonstrate using Laravel's queue system to offload heavy file processing after the upload is confirmed, ensuring the initial response remains lightweight and responsive.

When deciding between raw PHP and a framework, consider your deployment environment. If you are on shared hosting or an older PHP version (pre-8.0), manual stream management is fraught with pitfalls regarding memory limits and header flushing. Modern environments often support stream_wrapper_register solutions that make progress tracking easier, but they require specific configuration in .htaccess or nginx.conf.

Ultimately, the decision to implement a progress bar depends on your stack's ability to handle partial requests. If you choose to build it yourself, ensure your server sends the correct headers and that your client-side JavaScript handles the asynchronous updates gracefully. If you need a production-ready solution quickly, integrating with a framework like Laravel is the path of least resistance, allowing you to focus on album logic rather than low-level stream manipulation.

Our network