PHP cURL使用小结
cURL简介
-
cURL是什么？
cURL（Client URL Library Functions）由 Daniel Stenberg 创建的libcurl库，官方定义为：curl is a command line tool for transferring data with URL syntax，即使用URL语法传输数据的命令行工具，cURL是客户端向服务器请求资源的工具，其他的方式有file_get_contents()、file()、readfile()等。缺点是：不能完成cookies、验证、表单提交、文件上传这些操作，支持的协议少。curl允许你与各种的服务器使用各种类型的协议进行连接和通讯。libcurl目前支持http、https、ftp、gopher、telnet、dict、file和ldap协议。libcurl同时也支持HTTPS认证、HTTP POST、HTTP PUT、 FTP 上传(这个也能通过PHP的FTP扩展完成)、HTTP 基于表单的上传、代理、cookies和用户名+密码的认证。 -
什么时候用cURL?
- 网页爬虫
- 实现文件上传下载
- 模拟登陆
- 获取接口数据
- 所有网络上的资源都可以使用cURL访问和下载
- 如何使用cURL?
先开启扩展，linux下需要在编译PHP时在configure命令上加上“–with-curl” 参数,windows下在php.ini中将extension=php_curl.dll前面的分号去掉开启。 - 初始化(curl_init)
- 设置curl执行时相关选项(curl_setopt())
- 执行并获取结果(curl_exec())
- 释放资源(cURL句柄)(curl_close())
cURL常用函数
常规函数
-
curl_init()
作用
初始化一个cURL会话
语法
resource curl_init ([ string $url = NULL ] )
参数
url
如果提供了该参数，CURLOPT_URL 选项将会被设置成这个值。你也可以使用curl_setopt()函数手动地设置这个值
返回值
如果成功，返回一个cURL句柄，出错返回 FALSE -
curl_setopt()
作用
设置一个cURL传输选项
语法
bool curl_setopt ( resource $ch , int $option , mixed $value )
参数
$ch
由curl_init()返回的cURL句柄
$option
需要设置的CURLOPT_XXX选项
$value
设置在$option选项的值
常用选项
可以设置成布尔类型
CURLOPT_AUTOREFERER
当根据Location重定向时，自动设置header中的referer信息
CURLOPT_BINARYTRANSFER
在启用CURLOPT_RETURNTRANSFER的时候，返回原生的RAW输出
CURL_COOKIESESSION
启用时curl会仅仅传递一个session cookie，忽略其他的cookie。默认情况下cURL会将所有的cookie返回给服务端。
session cookie是指哪些用来判断服务器端的session是否有效而存在的cookie
CURLOPT_CRLF
启用时将Unix的换行符换成回车符
CURLOPT_FRESH_CONNECT
强制获取一个新的连接，替代缓存中的连接
CURLOPT_HEADER
启用时会将头文件的信息作为数据流输出
CURLOPT_NOBODY
启用时将不对HTML中的BODY部分进行输出
CURLOPT_POST
启用时会发送一个常规的POST请求，类型为：application/x-www-form-urlencodeed,就像表单提交一样
CURLOPT_PUT
启用时允许HTTP发送文件，必须同事设置CURLOPT_INFILE和CURLOPT_INFILESIZE
CURLOPT_RETURNTRANSFER
将curl_exec()获取的信息以文件流的形式返回，而不是直接输出
CURLOPT_UPLOAD
启用后允许文件上传
CURLOPT_SSL_VERIFYPEER
禁用后cURL将终止从服务端进行验证。使用CURLOPT_CAINFO选项设置证书使用CURLOPT_CAPATH选项设置证书目录 如果CURLOPT_SSL_VERIFYPEER(默认值为2)被启用，CURLOPT_SSL_VERIFYHOST需要被设置成TRUE否则设置为FALSE。
可以设置成整型的选项
CURLOPT_BUFFERSIZE
每次获取的数据中读入缓存的大小，但是不保证这个值每次都会被填满
CURLOPT_CONNECTTIMEOUT
在发起连接前等待的时间，如果设置为0，则无限等待
CURLOPT_CONNECTTIMEOUT_MS
尝试连接等待的时间，以毫秒为单位，如果设置为0，则无限等待
CURLOPT_INFILESIZE
设定上传文件的大小限制，字节(byte)为单位
CURLOPT_MAXCONNECTS
允许的最大连接数量，超过是会通过CURLOPT_CLOSEPOLICY决定应该停止哪些连接
CURLOPT_PORT
用来指定连接端口
CURLOPT_TIMEOUT
设置cURL允许执行的最长秒数
CURLOPT_TIMEOUT_MS
设置cURL允许执行的最长毫秒数。
CURLOPT_SSL_VERIFYHOST
1 检查服务器SSL证书中是否存在一个公用名(common name)。译者注：公用名(Common Name)一般来讲就是填写你将要申请SSL证书的域名 (domain)或子域名(sub domain)。2 检查公用名是否存在，并且是否与提供的主机名匹配
可以设置成字符串的选项
CURLOPT_COOKIE
设定HTTP请求中"Cookie: "部分的内容。多个cookie用分号分隔，分号后带一个空格(例如， "fruit=apple; colour=red")。
CURLOPT_COOKIEFILE
包含cookie数据的文件名，cookie文件的格式可以是Netscape格式，或者只是纯HTTP头部信息存入文件。
CURLOPT_COOKIEJAR
连接结束后保存cookie信息的文件。
CURLOPT_ENCODING
HTTP请求头中"Accept-Encoding: "的值。支持的编码有"identity"，"deflate"和"gzip"。如果为空字符串""，请求头会发送所有支持的编码类型
CURLOPT_POSTFIELDS
全部数据使用HTTP协议中的"POST"操作来发送。要发送文件，在文件名前面加上@前缀并使用完整路径。这个参数可以通过urlencoded后的字符串类似'para1=val1¶2=val2&...'或使用一个以字段名为键，字段数据为值的数组。如果value是一个数组，Content-Type头将会被设置成multipart/form-data
CURLOPT_REFERER
在HTTP请求头中"Referer: "的内容。
CURLOPT_URL
需要获取的URL地址，也可以在curl_init()函数中设置
CURLOPT_USERAGENT
在HTTP请求中包含一个"User-Agent: "头的字符串。
CURLOPT_USERPWD
传递一个连接中需要的用户名和密码，格式为："[username]:[password]"。
可以设置成数组的选项
CURLOPT_HTTPHEADER
一个用来设置HTTP头字段的数组。使用如下的形式的数组进行设置： array('Content-type: text/plain', 'Content-length: 100')
返回值
成功时返回 TRUE， 或者在失败时返回 FALSE -
curl_exec()
作用
执行一个cURL会话
语法
mixed curl_exec ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
成功时返回 TRUE， 或者在失败时返回 FALSE。
如果 CURLOPT_RETURNTRANSFER选项被设置，函数执行成功时会返回执行的结果，失败时返回 FALSE -
curl_close()
作用
关闭一个cURL会话
语法
void curl_close ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
没有返回值 -
curl_version()
作用
获取cURL版本信息 -
curl_setopt_array()
作用
为cURL传输会话批量设置选项
语法
bool curl_setopt_array ( resource $ch , array $options )
参数
$ch
由 curl_init() 返回的 cURL 句柄。
$options
一个array用来确定将被设置的选项及其值。数组的键值必须是一个有效的curl_setopt()常量或者是它们对等的整数值。
返回值
如果全部的选项都被成功设置，返回TRUE。如果一个选项不能被成功设置，马上返回FALSE，忽略其后的任何在options数组中的选项 -
curl_errno()
作用
返回最后一次的错误号
语法
int curl_errno ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
返回错误号或 0如果没有错误发生。 -
curl_error()
作用
返回一个保护当前会话最近一次错误的字符串
语法
string curl_error ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
返回错误信息或 '' (空字符串) 如果没有任何错误发生。 -
curl_strerror()
作用
返回错误代码的字符串描述
语法
string curl_strerror ( int $errornum )
参数
$errornum
一个cURL 错误码的常量。
返回值
返回错误码描述信息，非法错误码返回NULL 。 -
curl_escape()
作用
使用 URL 编码给定的字符串
语法
string curl_escape ( resource $ch , string $str )
参数
$ch
由 curl_init() 返回的 cURL 句柄
$str
需要编码的字符串
返回值
返回编码后的字符串 或者在失败时返回 FALSE。 -
curl_unescape()
作用
解码给定的 URL 编码的字符串
语法
string curl_unescape ( resource $ch , string $str )
参数
$ch
由 curl_init() 返回的 cURL 句柄
$str
需要解码的 URL 编码字符串
返回值
返回解码后的字符串 或者在失败时返回 FALSE。 -
curl_copy_handle()
作用
复制一个cURL句柄和它的所有选项
语法
resource curl_copy_handle ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
返回一个新的cURL句柄。 -
curl_file_create()
作用
创建一个 CURLFile 对象
语法
CURLFile curl_file_create ( string $filename [, string $mimetype [, string $postname ]] )
参数
$filename
上传文件的路径
$mimetype
文件的MIME类型
$postname
文件名
返回值
CURLFile对象 -
curl_reset()
作用
重置libcurl会话句柄的所有选项
语法
void curl_reset ( resource $ch )
参数
由 curl_init() 返回的 cURL 句柄。
返回值
没有返回值 -
curl_getinfo()
作用
获取一个cURL连接资源句柄的信息
语法
mixed curl_getinfo ( resource $ch [, int $opt = 0 ] )
参数
$ch
由 curl_init() 返回的 cURL 句柄
$opt
CURLINFO_EFFECTIVE_URL - 最后一个有效的URL地址
◦ CURLINFO_HTTP_CODE - 最后一个收到的HTTP代码
◦ CURLINFO_FILETIME - 远程获取文档的时间，如果无法获取，则返回值为"-1"
◦ CURLINFO_TOTAL_TIME - 最后一次传输所消耗的时间
◦ CURLINFO_NAMELOOKUP_TIME - 名称解析所消耗的时间
◦ CURLINFO_CONNECT_TIME - 建立连接所消耗的时间
◦ CURLINFO_PRETRANSFER_TIME - 从建立连接到准备传输所使用的时间
◦ CURLINFO_STARTTRANSFER_TIME - 从建立连接到传输开始所使用的时间
◦ CURLINFO_REDIRECT_TIME - 在事务传输开始前重定向所使用的时间
◦ CURLINFO_SIZE_UPLOAD - 上传数据量的总值
◦ CURLINFO_SIZE_DOWNLOAD - 下载数据量的总值
◦ CURLINFO_SPEED_DOWNLOAD - 平均下载速度
◦ CURLINFO_SPEED_UPLOAD - 平均上传速度
◦ CURLINFO_HEADER_SIZE - header部分的大小
◦ CURLINFO_HEADER_OUT - 发送请求的字符串
◦ CURLINFO_REQUEST_SIZE - 在HTTP请求中有问题的请求的大小
◦ CURLINFO_SSL_VERIFYRESULT - 通过设置CURLOPT_SSL_VERIFYPEER返回的SSL证书验证请求的结果
◦ CURLINFO_CONTENT_LENGTH_DOWNLOAD - 从Content-Length: field中读取的下载内容长度
◦ CURLINFO_CONTENT_LENGTH_UPLOAD - 上传内容大小的说明
◦ CURLINFO_CONTENT_TYPE - 下载内容的Content-Type:值，NULL表示服务器没有发送有效的Content-Type: header
返回值
如果 opt 被设置，以字符串形式返回它的值。否则，返回返回一个包含下列元素的关联数组(它们分别对应于 opt):
"url"
◦ "content_type"
◦ "http_code"
◦ "header_size"
◦ "request_size"
◦ "filetime"
◦ "ssl_verify_result"
◦ "redirect_count"
◦ "total_time"
◦ "namelookup_time"
◦ "connect_time"
◦ "pretransfer_time"
◦ "size_upload"
◦ "size_download"
◦ "speed_download"
◦ "speed_upload"
◦ "download_content_length"
◦ "upload_content_length"
◦ "starttransfer_time"
◦ "redirect_time"
多线程函数
-
curl_multi_init()
作用
返回一个新cURL批处理句柄
语法
resource curl_multi_init ( void )
返回值
成功时返回一个cURL批处理句柄，失败时返回FALSE。 -
curl_multi_setopt()
作用
为cURL并行处理设置一个选项
语法
bool curl_multi_setopt ( resource $mh , int $option , mixed $value )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。
$option
常量CURLMOPT_*之一
$value
需要设置给$option选项的值
返回值
成功时返回 TRUE， 或者在失败时返回 FALSE。 -
curl_multi_exec()
作用
运行当前 cURL 句柄的子连接
语法
int curl_multi_exec ( resource $mh , int &$still_running )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。
$still_running
一个用来判断操作是否仍在执行的标识的引用
返回值
一个定义于 cURL 预定义常量中的 cURL 代码。 -
curl_multi_close()
作用
关闭一组cURL句柄
语法
void curl_multi_close ( resource $mh )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。 -
curl_multi_add_handle()
作用
向curl批处理会话中添加单独的curl句柄
语法
int curl_multi_add_handle ( resource $mh , resource $ch )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。
$ch
由 curl_init() 返回的 cURL 句柄。
返回值
成功时返回0，失败时返回CURLM_XXX之一的错误码 -
curl_multi_getcontent()
作用
如果设置了CURLOPT_RETURNTRANSFER，则返回获取的输出的文本流
语法
string curl_multi_getcontent ( resource $ch )
参数
$ch
由 curl_init() 返回的 cURL 句柄。
返回值
如果设置了CURLOPT_RETURNTRANSFER，则返回获取的输出的文本流。 -
curl_multi_info_read()
作用
获取当前解析的cURL的相关传输信息
语法
array curl_multi_info_read ( resource $mh [, int &$msgs_in_queue = NULL ] )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。
$msgs_in_queue
仍在队列中的消息数量
返回值
成功时返回相关信息的数组，失败时返回FALSE。 -
curl_multi_remove_handle()
作用
移除curl批处理句柄资源中的某个句柄资源
语法
int curl_multi_remove_handle ( resource $mh , resource $ch )
参数
$mh
由 curl_multi_init() 返回的 cURL 多个句柄。
$ch
由 curl_init() 返回的 cURL 句柄。
返回值
成功时返回一个cURL句柄，失败时返回FALSE。 -
curl_multi_strerror()
作用
返回描述错误码的字符串文本
语法
string curl_multi_strerror ( int $errornum )
参数
$errornum
一个CURLM error codes错误码常量
返回值
返回描述错误码的字符串文本, 否则返回 NULL。
