Ref/curl-Phpdoc专题

curl_close

关闭 cURL 会话

说明

void <span class="methodname">curl_close ( <span class="type">resource $ch )

关闭 cURL 会话并且释放所有资源。cURL 句柄 ch 也会被删除。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

没有返回值。

范例

示例 #1 初始化新的 cURL 会话，并获取一张网页

<?php
// 创建一个新cURL资源
$ch = curl_init();

// 设置URL和相应的选项
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// 抓取URL并把它传递给浏览器
curl_exec($ch);

// 关闭cURL资源，并且释放系统资源
curl_close($ch);
?>

参见

• curl_init
• curl_multi_close

curl_copy_handle

复制一个cURL句柄和它的所有选项

说明

resource <span class="methodname">curl_copy_handle ( <span class="methodparam">resource $ch )

复制一个cURL句柄并保持相同的选项。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

返回一个新的cURL句柄。

范例

示例 #1 复制一个cURL句柄

<?php
// 创建一个新的cURL资源
$ch = curl_init();

// 设置URL和相应的选项
curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/');
curl_setopt($ch, CURLOPT_HEADER, 0);

// 复制句柄
$ch2 = curl_copy_handle($ch);

// 抓取URL (http://www.example.com/) 并把它传递给浏览器
curl_exec($ch2);

// 关闭cURL资源，并且释放系统资源
curl_close($ch2);
curl_close($ch);
?>

curl_errno

返回最后一次的错误代码

说明

int <span class="methodname">curl_errno ( <span class="type">resource $ch )

返回最后一次 cURL 操作的错误代码。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

返回错误代码或在没有错误发生时返回 0 (零)。

范例

示例 #1 curl_errno 例子

<?php
// 创建 cURL 句柄，指向不存在的位置
$ch = curl_init('http://404.php.net/');

// 执行
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);

// 检查是否有错误发生
if(curl_errno($ch))
{
    echo 'Curl error: ' . curl_error($ch);
}

// 关闭句柄
curl_close($ch);
?>

参见

• curl_error
• » Curl 错误代码

curl_error

返回当前会话最后一次错误的字符串

说明

string <span class="methodname">curl_error ( <span class="type">resource $ch )

返回最近一次 cURL 操作的文本错误详情。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

返回错误信息，或者如果没有任何错误发生就返回 '' (空字符串)。

范例

示例 #1 curl_error 例子

<?php
// 创建 cURL 句柄，指向一个不存在的位置
$ch = curl_init('http://404.php.net/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

if(curl_exec($ch) === false)
{
    echo 'Curl error: ' . curl_error($ch);
}
else
{
    echo '操作完成没有任何错误';
}

// 关闭句柄
curl_close($ch);
?>

参见

• curl_errno
• » Curl 错误代码

curl_escape

使用 URL 编码给定的字符串

说明

string <span class="methodname">curl_escape ( <span class="type">resource $ch , <span class="methodparam">string $str )

该函数使用 URL 根据» RFC 3986编码给定的字符串。

参数

handle
由 curl_init 返回的 cURL 句柄。

str
需要编码的字符串

返回值

返回编码后的字符串 或者在失败时返回 false。

范例

示例 #1 curl_escape 示例

<?php
// 创建一个 curl 句柄
$ch = curl_init();

// 把编码后的字符串当做一个 GET 参数
$location = curl_escape($ch, 'Hofbräuhaus / München');
// 结果： Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// 用编码好的字符串组装一个 URL
$url = "http://example.com/add_location.php?location={$location}";
// 结果： http://example.com/add_location.php?location=Hofbr%C3%A4uhaus%20%2F%20M%C3%BCnchen

// 发送 HTTP 请求并关闭句柄
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
curl_close($ch);
?>

参见

• curl_unescape
• urlencode
• rawurlencode
• » RFC 3986

curl_exec

执行 cURL 会话

说明

mixed <span class="methodname">curl_exec ( <span class="type">resource $ch )

执行给定的 cURL 会话。

这个函数应该在初始化一个 cURL 会话并且全部的选项都被设置后被调用。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

成功时返回 true， 或者在失败时返回 false。 然而，如果 设置了 CURLOPT_RETURNTRANSFER 选项，函数执行成功时会返回执行的结果，失败时返回 false 。

Warning

此函数可能返回布尔值 false，但也可能返回等同于 false 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

Note:

注意：响应代码是错误码时（例如404 Not found）也不会被当作失败。这种情况可以使用 <span class="function">curl_getinfo 来检查。

范例

示例 #1 获取网页

<?php
// 创建新的 cURL 资源
$ch = curl_init();

// 设置 URL 和相应的选项
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// 抓取 URL 并把它传递给浏览器
curl_exec($ch);

// 关闭 cURL 资源，并且释放系统资源
curl_close($ch);
?>

参见

• curl_multi_exec

curl_file_create

创建一个 CURLFile 对象

说明

此函数是该函数的别名： <span class="methodname">CURLFile::__construct

curl_getinfo

获取一个cURL连接资源句柄的信息

说明

mixed <span class="methodname">curl_getinfo ( <span class="methodparam">resource $ch [, int $opt<span class="initializer"> = 0 ] )

获取最后一次传输的相关信息。

参数

handle
由 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"

更新日志

范例

示例 #1 curl_getinfo example

<?php
// 创建一个cURL句柄
$ch = curl_init('http://www.yahoo.com/');

// 执行
curl_exec($ch);

// 检查是否有错误发生
if(!curl_errno($ch))
{
 $info = curl_getinfo($ch);

 echo 'Took ' . $info['total_time'] . ' seconds to send a request to ' . $info['url'];
}

// Close handle
curl_close($ch);
?>

注释

Note:

Information gathered by this function is kept if the handle is re-used. This means that unless a statistic is overridden internally by this function, the previous info is returned.

curl_init

初始化 cURL 会话

说明

resource <span class="methodname">curl_init ([ <span class="type">string $url = null ] )

初始化新的会话，返回 cURL 句柄，供<span class="function">curl_setopt、 <span class="function">curl_exec 和 <span class="function">curl_close 函数使用。

参数

url
如果提供了该参数，CURLOPT_URL 选项将会被设置成这个值。你也可以使用<span class="function">curl_setopt函数手动地设置这个值。

Note:

如果设置了 open_basedir，file 协议会被 cURL 禁用。

返回值

如果成功，返回 cURL 句柄，出错返回 false。

范例

示例 #1 初始化新的 cURL 会话并获取一个网页

<?php
// 创建一个新cURL资源
$ch = curl_init();

// 设置URL和相应的选项
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, 0);

// 抓取URL并把它传递给浏览器
curl_exec($ch);

// 关闭cURL资源，并且释放系统资源
curl_close($ch);
?>

参见

• curl_close
• curl_multi_init

curl_multi_add_handle

向curl批处理会话中添加单独的curl句柄

说明

int <span class="methodname">curl_multi_add_handle ( <span class="methodparam">resource $mh , resource $ch )

增加 ch 句柄到批处理会话mh

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

handle
由 curl_init 返回的 cURL 句柄。

返回值

成功时返回0，失败时返回CURLM_XXX之一的错误码。

范例

示例 #1 curl_multi_add_handle example

这个范例将会创建2个cURL句柄，把它们加到批处理句柄，然后并行地运行它们。

<?php
// 创建一对cURL资源
$ch1 = curl_init();
$ch2 = curl_init();

// 设置URL和相应的选项
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// 创建批处理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$running=null;
// 执行批处理句柄
do {
    curl_multi_exec($mh,$running);
} while($running > 0);

// 关闭全部句柄
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);
?>

参见

• curl_multi_remove_handle
• curl_multi_init
• curl_init

curl_multi_close

关闭一组cURL句柄

说明

void <span class="methodname">curl_multi_close ( <span class="methodparam">resource $mh )

关闭一组cURL句柄。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

返回值

没有返回值。

范例

示例 #1 curl_multi_close example

这个范例将会创建2个cURL句柄，把它们加到批处理句柄，然后并行地运行它们。

<?php
// 创建一对cURL资源
$ch1 = curl_init();
$ch2 = curl_init();

// 设置URL和相应的选项
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// 创建批处理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$running=null;
// 执行批处理句柄
do {
    curl_multi_exec($mh,$running);
} while ($running > 0);

// 关闭全部句柄
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参见

• curl_multi_init
• curl_close

curl_multi_errno

返回上一次 curl 批处理的错误码

说明

int <span class="methodname">curl_multi_errno ( <span class="methodparam">resource $mh )

返回一个整型数字，为上次 curl 批处理错误码。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

返回值

返回整型数字，包含上次 curl 批处理的错误码， 或者在失败时返回 false

参见

• curl_errno

curl_multi_exec

运行当前 cURL 句柄的子连接

说明

int <span class="methodname">curl_multi_exec ( <span class="methodparam">resource $mh , int &$still_running )

处理在栈中的每一个句柄。无论该句柄需要读取或写入数据都可调用此方法。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

still_running
一个用来判断操作是否仍在执行的标识的引用。

返回值

一个定义于 cURL 预定义常量中的 cURL 代码。

Note:

该函数仅返回关于整个批处理栈相关的错误。即使返回 CURLM_OK 时单个传输仍可能有问题。

范例

示例 #1 curl_multi_exec example

这个范例将会创建 2 个 cURL 句柄，把它们加到批处理句柄，然后并行地运行它们。

<?php
// 创建一对cURL资源
$ch1 = curl_init();
$ch2 = curl_init();

// 设置URL和相应的选项
curl_setopt($ch1, CURLOPT_URL, "http://lxr.php.net/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// 创建批处理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$active = null;
// 执行批处理句柄
do {
    $mrc = curl_multi_exec($mh, $active);
} while ($mrc == CURLM_CALL_MULTI_PERFORM);

while ($active && $mrc == CURLM_OK) {
    if (curl_multi_select($mh) != -1) {
        do {
            $mrc = curl_multi_exec($mh, $active);
        } while ($mrc == CURLM_CALL_MULTI_PERFORM);
    }
}

// 关闭全部句柄
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参见

• curl_multi_init
• curl_multi_select
• curl_exec

curl_multi_getcontent

如果设置了CURLOPT_RETURNTRANSFER，则返回获取的输出的文本流

说明

string <span class="methodname">curl_multi_getcontent ( <span class="methodparam">resource $ch )

如果CURLOPT_RETURNTRANSFER作为一个选项被设置到一个具体的句柄，那么这个函数将会以字符串的形式返回那个cURL句柄获取的内容。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

如果设置了CURLOPT_RETURNTRANSFER，则返回获取的输出的文本流。

参见

• curl_multi_init

curl_multi_info_read

获取当前解析的cURL的相关传输信息

说明

array <span class="methodname">curl_multi_info_read ( <span class="methodparam">resource $mh [, int &$msgs_in_queue = null ] )

查询批处理句柄是否单独的传输线程中有消息或信息返回。消息可能包含诸如从单独的传输线程返回的错误码或者只是传输线程有没有完成之类的报告。

重复调用这个函数，它每次都会返回一个新的结果，直到这时没有更多信息返回时，false 被当作一个信号返回。通过msgs_in_queue返回的整数指出将会包含当这次函数被调用后，还剩余的消息数。

Warning

返回的资源指向的数据调用<span class="function">curl_multi_remove_handle后将不会存在。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

msgs_in_queue
仍在队列中的消息数量。

返回值

成功时返回相关信息的数组，失败时返回false。

范例

示例 #1 一个<span class="function">curl_multi_info_read范例

<?php

$urls = array(
   "http://www.cnn.com/",
   "http://www.bbc.co.uk/",
   "http://www.yahoo.com/"
);

$mh = curl_multi_init();

foreach ($urls as $i => $url) {
    $conn[$i] = curl_init($url);
    curl_setopt($conn[$i], CURLOPT_RETURNTRANSFER, 1);
    curl_multi_add_handle($mh, $conn[$i]);
}

do {
    $status = curl_multi_exec($mh, $active);
    $info = curl_multi_info_read($mh);
    if (false !== $info) {
        var_dump($info);
    }
} while ($status === CURLM_CALL_MULTI_PERFORM || $active);

foreach ($urls as $i => $url) {
    $res[$i] = curl_multi_getcontent($conn[$i]);
    curl_close($conn[$i]);
}

var_dump(curl_multi_info_read($mh));

?>

以上例程的输出类似于：

array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(5) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(7) of type (curl)
}
array(3) {
  ["msg"]=>
  int(1)
  ["result"]=>
  int(0)
  ["handle"]=>
  resource(6) of type (curl)
}
bool(false)

更新日志

参见

• curl_multi_init

curl_multi_init

返回一个新cURL批处理句柄

说明

resource <span class="methodname">curl_multi_init ( <span class="methodparam">void )

允许并行地处理批处理cURL句柄。

参数

此函数没有参数。

返回值

成功时返回一个cURL批处理句柄，失败时返回false。

范例

示例 #1 curl_multi_init example

这个范例将会创建2个cURL句柄，把它们加到批处理句柄，然后并行地运行它们。

<?php
// 创建一对cURL资源
$ch1 = curl_init();
$ch2 = curl_init();

// 设置URL和相应的选项
curl_setopt($ch1, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch1, CURLOPT_HEADER, 0);
curl_setopt($ch2, CURLOPT_URL, "http://www.php.net/");
curl_setopt($ch2, CURLOPT_HEADER, 0);

// 创建批处理cURL句柄
$mh = curl_multi_init();

// 增加2个句柄
curl_multi_add_handle($mh,$ch1);
curl_multi_add_handle($mh,$ch2);

$running=null;
// 执行批处理句柄
do {
    usleep(10000);
    curl_multi_exec($mh,$running);
} while ($running > 0);

// 关闭全部句柄
curl_multi_remove_handle($mh, $ch1);
curl_multi_remove_handle($mh, $ch2);
curl_multi_close($mh);

?>

参见

• curl_init
• curl_multi_close

curl_multi_remove_handle

移除cURL批处理句柄资源中的某个句柄资源

说明

int <span class="methodname">curl_multi_remove_handle ( <span class="methodparam">resource $mh , resource $ch )

从给定的批处理句柄mh中移除ch句柄。当ch句柄被移除以后，仍然可以合法地用<span class="function">curl_exec执行这个句柄。如果要移除的句柄正在被使用，则这个句柄涉及的所有传输任务会被中止。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

handle
由 curl_init 返回的 cURL 句柄。

返回值

成功时返回0，失败时返回CURLM_XXX中的一个。

参见

• curl_init
• curl_multi_init
• curl_multi_add_handle

curl_multi_select

等待所有cURL批处理中的活动连接

说明

int <span class="methodname">curl_multi_select ( <span class="methodparam">resource $mh [, float $timeout = 1.0 ] )

阻塞直到cURL批处理连接中有活动连接。

参数

multi_handle
由 curl_multi_init 返回的 cURL 多个句柄。

timeout
以秒为单位，等待响应的时间。

返回值

成功时返回描述符集合中描述符的数量。失败时，select失败时返回-1，否则返回超时(从底层的select系统调用).

参见

• curl_multi_init

curl_multi_setopt

为 cURL 并行处理设置一个选项

说明

bool <span class="methodname">curl_multi_setopt ( <span class="methodparam">resource $mh , int $option , mixed $value )

Warning

本函数还未编写文档，仅有参数列表。

参数

mh

option
常量 *`CURLMOPT_`** 之一。

value
将要设置给 option 的值。

在 option 参数为下列值时 value 需要为 int 类型：

返回值

成功时返回 true， 或者在失败时返回 false。

curl_multi_strerror

返回字符串描述的错误代码

说明

string <span class="methodname">curl_multi_strerror ( <span class="methodparam">int $errornum )

返回一个用以描述所给 CURLM 错误代码所对应的错误信息。

参数

errornum
» CURLM 错误代码中的常量之一。

返回值

返回可用错误代码所对应的错误信息，否则返回 null 。

范例

示例 #1 curl_multi_strerror 函数的范例：

<?php
// Create cURL handles
$ch1 = curl_init("http://example.com"/);
$ch2 = curl_init("http://php.net/");

// Create a cURL multi handle
$mh = curl_multi_init();

// Add the handles to the multi handle
curl_multi_add_handle($mh, $ch1);
curl_multi_add_handle($mh, $ch2);

// Execute the multi handle
do {
    $status = curl_multi_exec($mh, $active);
    // Check for errors
    if($status > 0) {
        // Display error message
        echo "ERROR!\n " . curl_multi_strerror($status);
    }
} while ($status === CURLM_CALL_MULTI_PERFORM || $active);
?>

参见

• curl_strerror
• » cURL error codes

curl_pause

暂停和取消暂停一个连接。

说明

int <span class="methodname">curl_pause ( <span class="type">resource $ch , <span class="methodparam">int $bitmask )

Warning

本函数还未编写文档，仅有参数列表。

参数

handle
由 curl_init 返回的 cURL 句柄。

bitmask
*`CURLPAUSE_`** 常量之一。

返回值

返回一个错误代码 (如果没有错误则返回CURLE_OK常量)。

curl_reset

重置一个 libcurl 会话句柄的所有的选项

说明

void <span class="methodname">curl_reset ( <span class="type">resource $ch )

该函数将给定的 cURL 句柄所有选项重新设置为默认值。

参数

handle
由 curl_init 返回的 cURL 句柄。

返回值

没有返回值。

范例

示例 #1 curl_reset 示例

<?php
// 创建一个url 句柄
$ch = curl_init();

// 设置 CURLOPT_USERAGENT 选项
curl_setopt($ch, CURLOPT_USERAGENT, "My test user-agent");

// 重置所有的预先设置的选项
curl_reset($ch);

// 发送 HTTP 请求
curl_setopt($ch, CURLOPT_URL, 'http://example.com/');
curl_exec($ch); // 预先设置的 user-agent 不会被发送，它已经被 curl_reset 重置掉了

// 关闭句柄
curl_close($ch);
?>

注释

Note:

curl_reset also resets the URL given as the curl_init parameter.

参见

• curl_setopt

curl_setopt_array

为 cURL 传输会话批量设置选项

说明

bool <span class="methodname">curl_setopt_array ( <span class="methodparam">resource $ch , array $options )

为 cURL 传输会话批量设置选项。这个函数对于需要设置大量的 cURL 选项是非常有用的，不需要重复地调用 <span class="function">curl_setopt。

参数

handle
由 curl_init 返回的 cURL 句柄。

options
一个 array 用来确定将被设置的选项及其值。数组的键值必须是一个有效的<span class="function">curl_setopt常量或者是它们对等的整数值。

返回值

如果全部的选项都被成功设置，返回true。如果一个选项不能被成功设置，马上返回false，忽略其后的任何在options数组中的选项。

范例

示例 #1 初始化新的 cURL 会话并抓取 web 页面

<?php
// 创建一个新 cURL 资源
$ch = curl_init();

// 设置 URL 和相应的选项
$options = array(CURLOPT_URL => 'http://www.example.com/',
                 CURLOPT_HEADER => false
                );

curl_setopt_array($ch, $options);

// 抓取 URL 并把它传递给浏览器
curl_exec($ch);

// 关闭 cURL 资源，并且释放系统资源
curl_close($ch);
?>

早于PHP 5.1.3这个函数可以做如下模拟：

示例 #2 我们对<span class="function">curl_setopt_array的等价实现

<?php
if (!function_exists('curl_setopt_array')) {
   function curl_setopt_array(&$ch, $curl_options)
   {
       foreach ($curl_options as $option => $value) {
           if (!curl_setopt($ch, $option, $value)) {
               return false;
           } 
       }
       return true;
   }
}
?>

注释

Note:

就<span class="function">curl_setopt来说，传递一个数组到CURLOPT_POST将会把数据以multipart/form-data的方式编码，然而传递一个URL-encoded字符串将会以application/x-www-form-urlencoded的方式对数据进行编码。

参见

• curl_setopt

curl_setopt

设置 cURL 传输选项

说明

bool <span class="methodname">curl_setopt ( <span class="type">resource $ch , <span class="methodparam">int $option , mixed $value )

为 cURL 会话句柄设置选项。

参数

handle
由 curl_init 返回的 cURL 句柄。

option
需要设置的CURLOPT_XXX选项。

value
将设置在option选项上的值。

以下 option 参数的 value应该被设置成 bool 类型：

以下 option的value应该被设置成 integer：

对于下面的这些option，value应该被设置成 <span class="type">string：

以下option，value应该被设置成数组：

以下 option，value应该被设置成流资源 （例如使用<span class="function">fopen）：

以下option 的 value应该是有效的函数或者闭包：

其他值：

返回值

成功时返回 true， 或者在失败时返回 false。

更新日志

范例

示例 #1 初始化一个新的cURL会话并获取一个网页

<?php
// 创建一个新cURL资源
$ch = curl_init();

// 设置URL和相应的选项
curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
curl_setopt($ch, CURLOPT_HEADER, false);

// 抓取URL并把它传递给浏览器
curl_exec($ch);

//关闭cURL资源，并且释放系统资源
curl_close($ch);
?>

示例 #2 上传文件 (PHP 5.5.0 后被废弃)

<?php

/* http://localhost/upload.php:
print_r($_POST);
print_r($_FILES);
*/

$ch = curl_init();

$data = array('name' => 'Foo', 'file' => '@/home/user/test.png');

curl_setopt($ch, CURLOPT_URL, 'http://localhost/upload.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false); //  PHP 5.6.0 后必须开启
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

curl_exec($ch);
?>

以上例程会输出：

Array
(
    [name] => Foo
)
Array
(
    [file] => Array
        (
            [name] => test.png
            [type] => image/png
            [tmp_name] => /tmp/phpcpjNeQ
            [error] => 0
            [size] => 279
        )

)

注释

Note:

传递一个数组到CURLOPT_POSTFIELDS，cURL会把数据编码成 multipart/form-data，而然传递一个URL-encoded字符串时，数据会被编码成 application/x-www-form-urlencoded。

参见

• curl_setopt_array

curl_share_close

关闭 cURL 共享句柄

说明

void <span class="methodname">curl_share_close ( <span class="methodparam">resource $sh )

关闭一个 cURL 共享句柄并且释放所有的资源。

参数

sh
由curl_share_init创建的 cURL 共享句柄。

返回值

没有返回值。

范例

示例 #1 curl_share_setopt 函数范例：

以下范例将会创建一个 cURL 共享句柄，并且往其中添加两个 cURL 句柄，最后共享这两个 cURL 句柄的 cookie 数据运行。

<?php
// Create cURL share handle and set it to share cookie data
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// Initialize the first cURL handle and assign the share handle to it
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// Execute the first cURL handle
curl_exec($ch1);

// Initialize the second cURL handle and assign the share handle to it
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// Execute the second cURL handle
//  all cookies from $ch1 handle are shared with $ch2 handle
curl_exec($ch2);

// Close the cURL share handle
curl_share_close($sh);

// Close the cURL handles
curl_close($ch1);
curl_close($ch2);
?>

参见

• curl_share_init

curl_share_errno

返回共享 curl 句柄的最后一次错误号

说明

int <span class="methodname">curl_share_errno ( <span class="methodparam">resource $sh )

返回一个整数，表示共享 curl 句柄的最后一次错误号

参数

sh
由 curl_share_init 函数创建的共享 cURL 句柄。

返回值

返回一个整数，表示共享 curl 句柄的最后一次错误号， 或者在失败时返回 false。

参见

• curl_errno

curl_share_init

初始化一个 cURL 共享句柄。

说明

resource <span class="methodname">curl_share_init ( <span class="methodparam">void )

运行在 cURL 句柄之间共享数据。

参数

此函数没有参数。

返回值

返回类型为"cURL 共享句柄"的资源。

范例

示例 #1 curl_share_init 函数的范例：

以下范例将会创建一个 cURL 共享句柄，并且往其中添加两个 cURL 句柄，最后用共享的 cookie 数据运行它们。

<?php
// 创建 cURL 共享句柄，并设置共享 cookie 数据
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// 初始化第一个 cURL 句柄，并将它设置到共享句柄
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// 执行第一个 cURL 句柄
curl_exec($ch1);

// 初始化第二个 cURL 句柄，并将它设置到共享句柄
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// 执行第二个 cURL 句柄
//  all cookies from $ch1 handle are shared with $ch2 handle
curl_exec($ch2);

// 关闭 cURL 共享句柄
curl_share_close($sh);

// 关闭 cURL 共享句柄
curl_close($ch1);
curl_close($ch2);
?>

参见

• curl_share_setopt
• curl_share_close

curl_share_setopt

为 cURL 共享句柄设置选项。

说明

bool <span class="methodname">curl_share_setopt ( <span class="methodparam">resource $sh , int $option , string $value )

为给定的 cURL 共享句柄设置一个选项。

参数

sh
一个由curl_share_init函数返回的 cURL 共享句柄。

option
| Option | Description | |-------------------------|--------------------------| | CURLSHOPT_SHARE | 指定要共享的数据类型。 | | CURLSHOPT_UNSHARE | 指定不再共享的数据类型。 |

value
| Value | Description | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------| | CURL_LOCK_DATA_COOKIE | 共享 cookie 数据。 | | CURL_LOCK_DATA_DNS | 共享 DNS 缓存。注意，当你使用 cURL 多句柄时，默认所有添加在同一个多句柄的句柄都将会共享 DNS 缓存。 | | CURL_LOCK_DATA_SSL_SESSION | 共享 SSL 的 session ID, 在重连同样的服务器时减少 SSL 握手时间。注意，SSL 的 session ID 在同一个的句柄中默认是重复使用的。 |

返回值

成功时返回 true， 或者在失败时返回 false。

范例

示例 #1 curl_share_setopt 函数的范例：

以下范例将会创建一个 cURL 共享句柄，并且往其中添加两个 cURL 句柄，最后共享这两个 cURL 句柄的 cookie 数据运行。

<?php
// Create cURL share handle and set it to share cookie data
$sh = curl_share_init();
curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);

// Initialize the first cURL handle and assign the share handle to it
$ch1 = curl_init("http://example.com/");
curl_setopt($ch1, CURLOPT_SHARE, $sh);

// Execute the first cURL handle
curl_exec($ch1);

// Initialize the second cURL handle and assign the share handle to it
$ch2 = curl_init("http://php.net/");
curl_setopt($ch2, CURLOPT_SHARE, $sh);

// Execute the second cURL handle
//  all cookies from $ch1 handle are shared with $ch2 handle
curl_exec($ch2);

// Close the cURL share handle
curl_share_close($sh);

// Close the cURL handles
curl_close($ch1);
curl_close($ch2);
?>

curl_share_strerror

返回错误号对应的错误消息

说明

string <span class="methodname">curl_share_strerror ( <span class="methodparam">int $errornum )

返回错误号对应的错误消息。

参数

errornum
» cURL error codes 常量。

返回值

返回错误消息。如果传入了无效的错误号，返回 null。

参见

• curl_share_errno
• curl_strerror

curl_strerror

返回错误代码的字符串描述

说明

string <span class="methodname">curl_strerror ( <span class="methodparam">int $errornum )

返回文本错误信息，解释了指定的错误代码。

参数

errornum
» cURL 错误代码中的常量之一。

返回值

返回错误信息描述，无效的错误代码返回 null 。

范例

示例 #1 curl_errno 函数的范例：

<?php
// 以错拼的 URL 协议创建 curl 句柄
$ch = curl_init("htp://example.com/");

// 发送请求
curl_exec($ch);

// 检测错误，显示错误信息
if($errno = curl_errno($ch)) {
    $error_message = curl_strerror($errno);
    echo "cURL error ({$errno}):\n {$error_message}";
}

// 关闭句柄
curl_close($ch);
?>

以上例程会输出：

cURL error (1):
 Unsupported protocol

参见

• curl_errno
• curl_error
• » Curl error codes

curl_unescape

解码给定的 URL 编码的字符串

说明

string <span class="methodname">curl_unescape ( <span class="methodparam">resource $ch , string $str )

该函数解码给定的 URL 编码的字符串。

参数

handle
由 curl_init 返回的 cURL 句柄。

str
需要解码的 URL 编码字符串

返回值

返回解码后的字符串 或者在失败时返回 false。

范例

示例 #1 curl_escape 示例

<?php
// 创建一个 curl 句柄
$ch = curl_init('http://example.com/redirect.php');

// 发送 HTTP 请求并且遵循重定向
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_exec($ch);

// 获取最后的有效 URL
$effective_url = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);
// 结果： "http://example.com/show_location.php?loc=M%C3%BCnchen"

// 解码这个 URL
$effective_url_decoded = curl_unescape($ch, $effective_url);
// "http://example.com/show_location.php?loc=München"

// 关闭句柄
curl_close($ch);
?>

注释

Note:

curl_unescape 不会将加号 (+) 解码成空格。而 urldecode 会。

参见

• curl_escape
• urlencode
• urldecode
• rawurlencode
• rawurldecode

curl_version

获取 cURL 版本信息

说明

array <span class="methodname">curl_version ([ <span class="methodparam">int $age<span class="initializer"> = CURLVERSION_NOW ] )

返回关于 cURL 版本的信息。

参数

age

返回值

返回关联数组，包含如下元素：

范例

示例 #1 curl_version 例子

这个范例将会检查当前 cURL 版本使用<span class="function">curl_version返回的 'features' 位掩码中哪些特性是可用的。

<?php
// 获取cURL版本数组
$version = curl_version();

// 在cURL编译版本中使用位域来检查某些特性
$bitfields = Array(
            'CURL_VERSION_IPV6', 
            'CURL_VERSION_KERBEROS4', 
            'CURL_VERSION_SSL', 
            'CURL_VERSION_LIBZ'
            );


foreach($bitfields as $feature)
{
    echo $feature . ($version['features'] & constant($feature) ? ' matches' : ' does not match');
    echo PHP_EOL;
}
?>

目录

• curl_close — 关闭 cURL 会话
• curl_copy_handle — 复制一个cURL句柄和它的所有选项
• curl_errno — 返回最后一次的错误代码
• curl_error — 返回当前会话最后一次错误的字符串
• curl_escape — 使用 URL 编码给定的字符串
• curl_exec — 执行 cURL 会话
• curl_file_create — 创建一个 CURLFile 对象
• curl_getinfo — 获取一个cURL连接资源句柄的信息
• curl_init — 初始化 cURL 会话
• curl_multi_add_handle — 向curl批处理会话中添加单独的curl句柄
• curl_multi_close — 关闭一组cURL句柄
• curl_multi_errno — 返回上一次 curl 批处理的错误码
• curl_multi_exec — 运行当前 cURL 句柄的子连接
• curl_multi_getcontent — 如果设置了CURLOPT_RETURNTRANSFER，则返回获取的输出的文本流
• curl_multi_info_read — 获取当前解析的cURL的相关传输信息
• curl_multi_init — 返回一个新cURL批处理句柄
• curl_multi_remove_handle — 移除cURL批处理句柄资源中的某个句柄资源
• curl_multi_select — 等待所有cURL批处理中的活动连接
• curl_multi_setopt — 为 cURL 并行处理设置一个选项
• curl_multi_strerror — 返回字符串描述的错误代码
• curl_pause — 暂停和取消暂停一个连接。
• curl_reset — 重置一个 libcurl 会话句柄的所有的选项
• curl_setopt_array — 为 cURL 传输会话批量设置选项
• curl_setopt — 设置 cURL 传输选项
• curl_share_close — 关闭 cURL 共享句柄
• curl_share_errno — 返回共享 curl 句柄的最后一次错误号
• curl_share_init — 初始化一个 cURL 共享句柄。
• curl_share_setopt — 为 cURL 共享句柄设置选项。
• curl_share_strerror — 返回错误号对应的错误消息
• curl_strerror — 返回错误代码的字符串描述
• curl_unescape — 解码给定的 URL 编码的字符串
• curl_version — 获取 cURL 版本信息