Guzzle 6 download file

Guzzle 6 download file

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

Stefan Bogdanescu

Founder & Senior Architect

Streamlining File Downloads in Guzzle 6

The core issue preventing a file from downloading directly to a browser when using GuzzleHttp\Client lies in how HTTP clients interact with servers versus how web browsers interpret responses. When you execute $client->request('GET', ...), Guzzle acts as a standard HTTP client. It receives the response stream and, by default, reads it entirely into memory or returns an object representing that stream. The browser has no involvement in this process because there is no active network request initiated by a browser instance; the code is running on a server-side environment (like PHP).

To trigger a download in a web browser, you must bypass the standard Guzzle response handling and instead provide raw HTML output that instructs the browser to open the stream. This requires two critical adjustments: disabling the automatic body reading of the Guzzle response and setting the correct Content-Disposition header within your application's HTTP response headers, not within the request headers sent to the API.

Handling the Response Stream

In your current implementation, you are sending a Content-Type: application/pdf header directly inside the $headers array passed to the request() method. This is technically incorrect for this use case. Request headers describe what you expect to receive or how you want the server to treat your request data (e.g., Accept, Authorization). They do not dictate how the client (Guzzle) should display the response body once it arrives.

Furthermore, Guzzle's default behavior upon a successful GET request is to read the stream into memory and populate $response->getBody(). If you simply return the $responsesfile object from your controller or service method, the framework (whether bare PHP, Laravel, or Symfony) will try to serialize or echo that object. Since it is not a string of HTML, nothing renders in the browser, and no download occurs.

You need to access the raw stream from Guzzle without consuming it. You can do this by calling getBody() on the response object and passing that stream directly to your output handler:

$responsesfile = $client->request('GET', 'documents/1234/content', [
    'headers' => [
        'Cache-Control' => 'no-cache',
        // Do not set Content-Type or Content-Disposition in request headers
        // These belong in the server response, not the client request
    ]
]);

// Get the raw stream
$body = $responsesfile->getBody();

// Output the stream directly to the browser without buffering
echo $body; 

Correcting Server-Side Headers

The logic for forcing a download resides entirely on the receiving end of your API, not in the Guzzle request configuration. The header Content-Disposition: attachment must be set by the server hosting the document (e.g., Node.js, Python, or another PHP backend), and the filename should ideally be derived from the stream's metadata if available, rather than hardcoded in the client request.

If you are building a Laravel application that wraps this Guzzle client, you should handle the response differently. Instead of echoing the raw body immediately, return the response object to your framework's controller layer. Laravel has built-in middleware that can read specific headers from incoming responses and redirect them to the user appropriately.

use Illuminate\Support\Facades\Http;

// Or using your custom Guzzle client injected into the service
$responsesfile = $client->request('GET', 'documents/1234/content');

return response($responsesfile->getBody(), 200)
    ->header('Content-Type', $responsesfile->getHeaderLine('Content-Type'))
    ->header('Content-Disposition', $responsesfile->getHeaderLine('Content-Disposition'));

However, if the API returning the file does not send the Content-Disposition header correctly in its response headers, you can force it on the output side. This ensures that even if the upstream service omits the header, your application enforces the download behavior.

Trade-offs and Pitfalls

One common pitfall is attempting to set Content-Type and Content-Disposition in the Guzzle request options as shown in your original snippet. This does nothing for the browser because these are request headers. The browser only reacts to response headers. Additionally, setting Cache-Control: no-cache in the request is unnecessary unless you are explicitly trying to prevent caching on the client side of your own application; usually, you want to let the server dictate caching policies via its own response headers.

Another consideration is memory usage. Streaming large files directly to echo or returning a raw stream avoids loading the entire file into RAM, which is crucial for high-performance applications. Guzzle's streaming capabilities make this seamless, but it requires you to explicitly pass the body to the output layer rather than relying on default serialization.

For more robust handling of file downloads within Laravel specifically, consider leveraging packages like spatie/laravel-response-file or ensuring your API responses include proper status codes (200 for success, 302 for redirects) and MIME types that match the file content. For deeper integration patterns regarding how to handle large file streams in a production environment, resources like https://laravelcompany.com often provide insights into optimizing response handling strategies.

Ultimately, the transition from "fetching data" to "downloading files" is a shift from treating the HTTP response as JSON or structured data to treating it as a raw byte stream that the browser must render based on server directives.

Our network