Posting multidimensional array with PHP and CURL

Posting multidimensional array with PHP and CURL

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

Stefan Bogdanescu

Founder & Senior Architect

Posting Multidimensional Arrays with PHP and cURL: Handling Multipart Forms Without Serialization

When you attempt to send an array containing nested structures via CURLOPT_POSTFIELDS without converting it to a string, standard PHP will throw an Array to string conversion error. This is the default behavior when passing an array directly to the option; however, if your goal is to maintain a multipart/form-data boundary and file upload capability, simply converting the entire payload to a query string using http_build_query() is not a viable solution. The standard library expects either a scalar string or an associative array for form fields, but it does not natively handle multidimensional arrays where a key contains another array of values in a way that aligns with standard HTML form submissions.

In the specific scenario described, the payload includes a name field that is itself an array holding multiple values (Jason, Mary, Lucy), alongside a file upload. The receiving server expects a specific format for this data. Because you cannot modify the receiver's code to handle serialized data or custom formats, and because you need to send files (which necessitates multipart/form-data), the approach of using the raw multidimensional array fails immediately upon execution.

The fundamental issue lies in how browsers and standard form submissions handle repeated fields. When a user selects multiple options for a single input field named name, the browser constructs the request body such that the key name appears multiple times, or it encodes the values sequentially within a specific structure depending on the server's configuration. Simply nesting an array under the key name in your local PHP script does not automatically translate to the correct serialized boundary format required by the receiving server for multipart data.

To resolve this without modifying the receiver, you must manually construct the request body string that mimics what a browser would send. This involves generating the proper multipart/form-data boundary string and formatting each field individually. You need to iterate through your local multidimensional array and expand it so that each value gets its own entry in the multipart stream with the correct key name.

Here is a practical approach to constructing the payload manually:

$boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW';
$postData = '';

foreach ($post as $key => $value) {
    if (is_array($value)) {
        // Handle multidimensional array by iterating through values
        foreach ($value as $itemValue) {
            $postData .= "--{$boundary}\r\n";
            $postData .= "Content-Disposition: form-data; name=\"{$key}\"\r\n\r\n";
            $postData .= htmlspecialchars($itemValue, ENT_QUOTES, 'UTF-8') . "\r\n";
        }
    } else {
        // Handle scalar values including file uploads
        $postData .= "--{$boundary}\r\n";
        if ($value === '@' . realpath('/test.txt')) {
            $postData .= "Content-Disposition: form-data; name=\"file\"; filename=\"test.txt\"\r\n";
            $postData .= "Content-Type: text/plain\r\n\r\n";
            // File content would be read and appended here, followed by \r\n--{$boundary}--\r\n
        } else {
            $postData .= "Content-Disposition: form-data; name=\"{$key}\"\r\n\r\n";
            $postData .= htmlspecialchars($value, ENT_QUOTES, 'UTF-8') . "\r\n";
        }
    }
}

$postData .= "--{$boundary}--\r\n";

curl_setopt($this->ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($this->ch, CURLOPT_HTTPHEADER, [
    "Content-Type: multipart/form-data; boundary={$boundary}"
]);

This method ensures that the name field is transmitted as multiple distinct parts within the multipart body rather than a single nested array element. This matches how most PHP servers parse incoming requests when they expect repeated keys. The trade-off here is increased complexity in the client-side code, but it preserves compatibility with standard form-handling logic on the server without requiring serialization libraries or custom deserialization functions.

If the receiving server uses Laravel, you might consider leveraging their framework's specific handling of multidimensional arrays if you had control over that environment, as Laravel often expects name to be an array in the request payload for Eloquent casting. However, since you lack access to the receiver, sticking to raw string construction is the only reliable path forward. Always ensure that file boundaries are strictly maintained and that special characters in your data are properly escaped to prevent parsing errors on the receiving end.

Our network