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

20

最近做的一个需求,要通过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明确指定顶层空间,防止代码包裹在命名空间内的时候崩掉。

注解

【注A】 好吧我知道assume不是件好事,不过有些实在过分浅显的事实,就容我下个最低限度的断言吧

你可能感兴趣的

19 条评论
公子 · 2014年10月16日

额,没次看沙大的文都感觉你写文的时候一定是开喷模式了吧-。-||
CURLOPT_SAFE_UPLOAD 这个东西为什么“推荐指定它的值”呢?总的来说像 http://us3.php.net/manual/en/function.curl-file-create.php#114538 这个代码一样有curlFile就用这个类,没有就用@不就行了?而且你也说过了5.6已经没有了@这个了,基本上两个东西就是互斥的啊...所以到底是为啥一定要纠结 SAFE_UPLOAD 这个选项-。-|||

回复

沙渺 作者 · 2014年10月16日

这么想来“产生不确定性的选项一律写死”也许只是个不必要的执念……

回复

tczzjin · 2014年10月16日

我觉得最大的问题出在开发环境和部署环境的php版本不一致...我们部署环境也是5.6,curl一起就切换了...

回复

过儿 · 2015年04月20日

大赞,,我一直找不到curl文件上传的问题,,百度了好久,,,我用的是5.6.5..手册还是前几个版本的,,一直找不到问题在哪里

回复

所言皆非 · 2015年06月23日

赞作者,不支持也不报错这个是有点坑,很不利于追查错误

回复

逗比大懒猪 · 2015年07月03日

不错, 正好解决问题了. 很多旧的帖子都没提新版本的方法. 我还是查官网说明才知道5.6的做法.后来自己服务器是5.3的,于是就学LZ的了.

回复

纸牌屋弗兰克 · 2015年08月04日

今天被这个问题坑了,本机是5.3,测试域是5.6,同事也是5.4以上,只有我机子可以传图,找半天原因,也想到了curl的问题,坑爹。。。

回复

纸牌屋弗兰克 · 2015年08月05日
//支持远程文件上传
if(empty($urlinfo['host'])){
    $tmp_name=dirname($file['tmp_name']).'/'.$file['title'].'.'.$file['extension'];//加上文件后缀
    rename($file['tmp_name'],$tmp_name);
    if(version_compare(phpversion(),'5.5.0') >= 0 && class_exists('CURLFile')){
        $fields['file'] = new CURLFile(realpath($tmp_name));
    }else{
        $fields['file'] = '@'.$tmp_name;//加@符号curl就会把它当成是文件上传处理
    }
}

我们测试域环境5.6,和线上环境5.4不一致,还是要这样改。。。

http://www.tantengvip.com/2015/08/php5-6-curl/

回复

杨佰 · 2015年11月03日

哈哈 知道了

回复

xuan · 2015年11月11日
巨逼 的神坑

回复

轩辕华美 · 2016年01月11日

if (class_exists('\CURLFile',false)) {

$field = array('fieldname' => new \CURLFile(realpath($filepath)));

} else {

$field = array('fieldname' => '@' . realpath($filepath));

}
这样写会不会更好?

回复

john328250389 · 2016年06月21日

感谢作者,解决了一个巨坑

回复

stois · 2016年08月08日

感谢作者。解决了一个巨坑 too

回复

zhang_sir · 2016年08月17日

和我遇到的问题简直一毛一样,非常感谢。

回复

wawahu · 2016年10月14日

请教一下 获取远程图片 不进行本地保存 直接POST上传到另一个网站 这个怎么操作呢?

回复

酷一西奥 · 2017年03月16日

For PHP < 5.5:

<?php

if (!function_exists('curl_file_create')) {

function curl_file_create($filename, $mimetype = '', $postname = '') {
    return "@$filename;filename="
        . ($postname ?: basename($filename))
        . ($mimetype ? ";type=$mimetype" : '');
}

}

?>

回复

丶波乐盖 · 2017年06月17日

特地注册账号来感谢楼主解决一大坑

回复

pader · 2017年10月12日

写的很好。但我并不觉得判断版本号是个不好的做法。

回复

人在WH · 2017年12月01日

太赞了, 楼主收下我的膝盖

回复

载入中...