考虑 PHP 5.0~5.6 各版本兼容性的 cURL 文件上传

转载自：http://segmentfault.com/blog/shamiao/1190000000725185

最近做的一个需求，要通过PHP调用cURL，以

multipart/form-data

格式上传文件。踩坑若干，够一篇文章了。

重要警告

没事不要读PHP的官方中文文档！版本跟不上坑死你！

不同版本PHP之间cURL的区别

PHP的cURL支持通过给

CURL_POSTFIELDS

传递关联数组（而不是字符串）来生成

multipart/form-data

的POST请求。

传统上，PHP的cURL支持通过在数组数据中，使用“

@

+文件全路径”的语法附加文件，供cURL读取上传。这与命令行直接调用cURL程序的语法是一致的：

curl_setopt(ch, CURLOPT_POSTFIELDS, array(
'file' => '@'.realpath('image.png'),
));
equals
$ curl -F "file=@/absolute/path/to/image.png" <url>

但PHP从5.5开始引入了新的CURLFile类用来指向文件。CURLFile类也可以详细定义MIME类型、文件名等可能出现在multipart/form-data数据中的附加信息。PHP推荐使用CURLFile替代旧的

@

语法：

curl_setopt(ch, CURLOPT_POSTFIELDS, [
'file' => new CURLFile(realpath('image.png')),
]);

PHP 5.5另外引入了

CURL_SAFE_UPLOAD

选项，可以强制PHP的cURL模块拒绝旧的

@

语法，仅接受CURLFile式的文件。5.5的默认值为false，5.6的默认值为true。

但是坑的一点在于：

@

语法在5.5就已经被打了deprecated，在5.6中就直接被删除了（会产生 ErorException: The usage of the

@filename

API for file uploading is deprecated. Please use the CURLFile class instead）。

对于PHP 5.6+而言，手动设置

CURL_SAFE_UPLOAD

为false是毫无意义的。根本不是字面意义理解的“设置成false，就能开启旧的unsafe的方式”——旧的方式已经作为废弃语法彻底不存在了。PHP 5.6+ == CURLFile only，不要有任何的幻想。

我的部署环境是5.4(仅

@

语法)，但开发环境是5.6(仅CURLFile)。都没有压在5.5这个两者都支持过渡版本上，结果就是必须写出带有环境判断的两套代码。

环境判断：小心魔法数字！

我见过这种环境判断的代码：

if (version_compare(phpversion(), '5.4.0') >= 0)

我对这种代码的评价只有一个字：屎。

这个判断掉入了典型的魔法数字陷阱。版本号莫名其妙的出现在代码之中，不查半天PHP手册和更新历史，很难明白作者被卡在了哪个功能的变更上。

代码应该回归本源。我们的实际需求其实是：有CURLFile就优先采用，没有再退化到传统

@

语法。那么代码就来了：

if (class_exists('\CURLFile')) {
$field = array('fieldname' => new \CURLFile(realpath($filepath)));
} else {
$field = array('fieldname' => '@' . realpath($filepath));
}

建议明确指定的退化选项

从可靠的角度，推荐指定

CURL_SAFE_UPLOAD

的值，明确告知php是容忍还是禁止旧的

@

语法。注意在低版本PHP中

CURLOPT_SAFE_UPLOAD

常量本身可能不存在，需要判断：

if (class_exists('\CURLFile')) {
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, true);
} else {
if (defined('CURLOPT_SAFE_UPLOAD')) {
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
}
}

cURL选项设置的顺序

不管是

curl_setopt()

单发还是

curl_setopt_array()

批量，cURL的选项总是设置一个生效一个，而设置好的选项立刻就会影响cURL在设置后续选项时的行为。

例如

CURLOPT_SAFE_UPLOAD

就和

CURLOPT_POSTFIELDS

的行为有关。如果先设置

CURLOPT_POSTFIELDS

再设置

CURLOPT_SAFE_UPLOAD

，那么后者的约束作用就不会生效。因为设置前者时cURL就已经把数据实际的识读处理完毕了！

cURL有那么几个选项存在这种坑，务必小心。还好这种存在“依赖关系”的选项不多，机制也不复杂，简单处理即可。我的方法是先批量设置所有的选项，然后直到

curl_exec()

的前一刻才用

curl_setopt()

单发设置

CURLOPT_POSTFIELDS

。

实际上在

curl_setopt_array()

用的数组中，保证

CURLOPT_POSTFIELDS

的位置在后边也是可靠的。PHP的关联数组是有顺序保障的，我们也可以假设

curl_setopt_array()

内部的执行顺序一定是从头到尾按顺序

[注A]

，所以尽可放心。

我的做法只是在代码表现上加个多余的保险，突出强调顺序的重要性防以后手贱。

命名空间

PHP 5.2或以下的版本没有命名空间。代码中用到了空间分隔符

\

就会引发解析器错误。要照顾PHP 5.2其实容易想，放弃命名空间即可。

要注意的反倒是有命名空间的PHP 5.3+。无论是调用CURLFile还是用

class_exists()

判断CURLFile的存在性，都推荐写成

\CURLFile

明确指定顶层空间，防止代码包裹在命名空间内的时候崩掉。

=============================================美丽的分割线=======================================================

众所周知，用curl上传只要设置4个变量即可（非HTTPS网站），那就是curlopt_url,curlopt_post,curlopt_returntransfer,curlopt_postfields，当然这4个都是大写。

curlopt_post,curlopt_returntransfer 都是 true，curlopt_url则是你要提交的网址，那么剩下的，curlopt_postfields就是你要上传的内容了。

上传文件在这里也变得非常简单，只需对应的值前面加个“@”即可，如curl_setopt($ch,CURLOPT_POSTFIELDS,array('file'=>'@/var/www/images/abc.jpg')); 文件通过realpath判断后存在的即可。

但是，这一切在php5.6里就发生了改成。php5.6不再支持@这样的上传方式，只能使用curl_file_create的方式来，所以上面的代码要改成

curl_setopt($ch,CURLOPT_POSTFIELDS,array('file'=>curl_file_create('/var/www/images/abc.jpg','image/jpg','abc')));

看看文档里怎么说：

CURLFile should be used to upload a file with CURLOPT_POSTFIELDS.

然后官网的手册中的最后一条评论，仿佛是看不下去，写了个处理上传的程序

There are "@" issue on multipart POST requests.

Solution for PHP 5.5 or later:
- Enable CURLOPT_SAFE_UPLOAD.
- Use CURLFile instead of "@".

Solution for PHP 5.4 or earlier:
- Build up multipart content body by youself.
- Change "Content-Type" header by yourself.

The following snippet will help you :D

<?php

/**
* For safe multipart POST request for PHP5.3 ~ PHP 5.4.
*
* @param resource $ch cURL resource
* @param array $assoc "name => value"
* @param array $files "name => path"
* @return bool
*/
function curl_custom_postfields($ch, array $assoc = array(), array $files = array()) {

// invalid characters for "name" and "filename"
static $disallow = array("\0", "\"", "\r", "\n");

// build normal parameters
foreach ($assoc as $k => $v) {
$k = str_replace($disallow, "_", $k);
$body[] = implode("\r\n", array(
"Content-Disposition: form-data; name=\"{$k}\"",
"",
filter_var($v),
));
}

// build file parameters
foreach ($files as $k => $v) {
switch (true) {
case false === $v = realpath(filter_var($v)):
case !is_file($v):
case !is_readable($v):
continue; // or return false, throw new InvalidArgumentException
}
$data = file_get_contents($v);
$v = call_user_func("end", explode(DIRECTORY_SEPARATOR, $v));
$k = str_replace($disallow, "_", $k);
$v = str_replace($disallow, "_", $v);
$body[] = implode("\r\n", array(
"Content-Disposition: form-data; name=\"{$k}\"; filename=\"{$v}\"",
"Content-Type: application/octet-stream",
"",
$data,
));
}

// generate safe boundary
do {
$boundary = "---------------------" . md5(mt_rand() . microtime());
} while (preg_grep("/{$boundary}/", $body));

// add boundary for each parameters
array_walk($body, function (&$part) use ($boundary) {
$part = "--{$boundary}\r\n{$part}";
});

// add final boundary
$body[] = "--{$boundary}--";
$body[] = "";

// set options
return @curl_setopt_array($ch, array(
CURLOPT_POST       => true,
CURLOPT_POSTFIELDS => implode("\r\n", $body),
CURLOPT_HTTPHEADER => array(
"Expect: 100-continue",
"Content-Type: multipart/form-data; boundary={$boundary}", // change Content-Type
),
));
}