Guzzle ~6.0 multipart and form_params

Guzzle ~6.0 multipart and form_params

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

Stefan Bogdanescu

Founder & Senior Architect

Guzzle ~6.0 multipart and form_params: Combining Fields and Files

When sending a request to an API that expects both simple form fields and file uploads, it is tempting to assume that simply providing both form_params and multipart options in a Guzzle client call will yield the desired result. However, Guzzle 6.x has a specific internal mechanism for handling multipart requests that causes one of these arrays to override the other depending on how the request is constructed.

In the scenario described, where $response = $client->post(...) is called with both form_params and multipart defined, the resulting HTTP body will contain only the file uploads specified in the multipart array. The fields listed in $request['form_params'] are completely ignored. This behavior occurs because Guzzle 6 treats the presence of a multipart key as an explicit directive to construct a multipart request entirely from that specific array. Once Guzzle enters "multipart mode," it discards any data provided via form_params to avoid ambiguity about which fields should be included in the boundary-separated body.

To successfully transmit both named form parameters and files in a single request, you must merge them into a single array before passing it to the multipart option. This unified approach ensures that Guzzle understands every field—whether it is a string value or a file resource—as part of the multipart stream. Here is how you should structure the request:

$response = $client->post('http://example.com/api', [
    'multipart' => [
        // Define simple form fields directly in the multipart array
        [
            'name'  => 'name',
            'contents' => 'Example name',
            'headers' => ['Content-Type' => 'text/plain']
        ],
        
        // Define file uploads alongside them
        [
            'name'     => 'image',
            'contents' => fopen('/path/to/image', 'r'),
            'filename' => '/path/to/image.jpg', // Optional but recommended
            'headers'  => ['Content-Type' => 'image/jpeg']
        ]
    ]
]);

By consolidating the data into a single multipart array, you preserve all necessary information. You can mix scalar values with file resources seamlessly. If your application relies on Guzzle 6.0 specifically, this merging strategy is the only supported method for combining these payload types.

It is worth noting that in later versions of Guzzle (7.x and beyond), the API evolved to allow passing form_params alongside multipart more intuitively without manual merging, but strict adherence to version 6.x requires this consolidation. When working with legacy codebases or specific containerized environments pinned to Guzzle 6, attempting to rely on separate keys will lead to silent data loss where your form fields simply vanish from the request body.

If you are building a solution that needs to handle complex upload scenarios across multiple frameworks, checking how a service like LaravelCompany handles file uploads might provide additional context on best practices for mixing metadata and binary content in HTTP requests. However, within the strict constraints of Guzzle 6's client configuration, the manual merging of arrays remains the definitive workaround.

Always verify the request body using tools like Postman or curl when debugging these issues to confirm that the fields are actually present before assuming the API has processed them correctly.

Our network