PHP cURL 多文件字段与数组表单数据混合提交的正确方法-php教程-PHP中文网

PHP cURL 多文件字段与数组表单数据混合提交的正确方法

本文详解如何使用 PHP cURL 同时上传文件并提交含重复键名的数组字段（如 colours[]），避免“Array to string conversion”和“415 Unsupported Media Type”错误，确保服务端正确接收 multipart/form-data 格式的结构化数据。

本文详解如何使用 php curl 同时上传文件并提交含重复键名的数组字段（如 `colours[]`），避免“array to string conversion”和“415 unsupported media type”错误，确保服务端正确接收 multipart/form-data 格式的结构化数据。

在 PHP 中通过 cURL 模拟 curl -F 命令提交带文件和数组字段的表单时，关键在于理解 CURLOPT_POSTFIELDS 对数组参数的处理机制：当传入关联数组且其中任意值为 CURLFile 对象时，cURL 会自动以 multipart/form-data 方式编码请求，并正确设置 Content-Type 和边界（boundary）；但 PHP 数组本身不支持重复键名（如多个 'colours[]'），因此不能直接使用 'colours' => ['red','yellow','blue'] —— 这会导致类型错误或服务端无法解析。

正确的做法是显式展开数组为带数字索引的键名格式，即把 colours[]="red" 转换为 'colours[0]' => 'red'、'colours[1]' => 'yellow' 等。这样既满足服务端对 colours 作为数组的语义要求（PHP 解析时会自动聚合成数组），又符合 cURL 对 CURLOPT_POSTFIELDS 数组键名的合法语法约束。

以下是完整、可运行的示例代码：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

$url = 'https://the.url.com/upload';
$file = '/path/to/the/file';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 确保返回响应内容
curl_setopt($ch, CURLOPT_HEADER, false);

// ✅ 正确构造 multipart 字段：文件 + 展开的数组索引键
$postFields = [
    'file' => curl_file_create($file),     // PHP 5.5+ 推荐方式（注意：不是 '@' 路径）
    'colours[0]' => 'red',
    'colours[1]' => 'yellow',
    'colours[2]' => 'blue',
];

curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);

curl_close($ch);

if ($error) {
    throw new RuntimeException("cURL error: {$error}");
}
if ($httpCode !== 200) {
    throw new RuntimeException("HTTP {$httpCode}: Upload failed");
}

echo "Upload successful:\n" . $response;

⚠️ 重要注意事项：

curl_file_create() 是 PHP 5.5+ 的标准方式，绝对不要混用旧式 '@' . $path 语法（已废弃且与 CURLOPT_POSTFIELDS 数组模式冲突）；
键名必须严格为 'colours[0]'、'colours[1]' 等形式，不能省略数字索引（如 'colours[]' 在数组中非法），也不能重复使用相同索引（如两个 'colours[0]' 会覆盖）；

若需动态生成数组字段，可用 array_map() 或循环构建：

$colours = ['red', 'yellow', 'blue'];
foreach ($colours as $i => $colour) {
    $postFields["colours[{$i}]"] = $colour;
}

服务端（如 PHP）收到后将自动解析 $_POST['colours'] 为数组 ['red','yellow','blue']，无需额外处理；
切勿对整个 $postFields 调用 http_build_query() —— 这会强制转为 application/x-www-form-urlencoded，丢失文件上传能力并触发 415 错误。

综上，核心原则是：用索引键模拟 HTML 表单的 name="colours[]" 语义，同时保持 cURL 数组参数的合法性。此方案兼容主流服务端框架（Laravel、Symfony、原生 PHP 等），是生产环境中稳定可靠的 multipart 数组提交实践。