README

THIS PACKAGE IS ABANDONNED PLEASE USE A MORE MODERN APPROACH LIKE guzzle

#Iris

Iris 是一个简单的库，它封装了 cURL 函数，以便于使用。 Iris 可以通过简单的 OOP 方法使用 cURL。

此包符合 PSR-1、PSR-2 和 PSR-4。

Iris 是为了理解 cURL 的高级特性而构建的。它松散地基于 phpmulticurl。

特性 & 路线图

• [待办] 添加单元测试

要求

您需要 PHP >= 5.3.0 和 cURL 扩展来使用 Iris，但推荐使用最新的稳定版 PHP。

安装

您可以使用 Composer 安装 Iris 包。

{
    "require": {
        "P\Iris": "0.*"
    }
}

或者，您可以下载库并指向其自动加载脚本。

<?php
require '/path/to/iris/autoload.php';

use P\Iris\Message;

$request = new Message;

使用

• 发送简单的请求
• 发送一批请求

文档

Iris\Message

实例化

要执行简单请求，您需要实例化 P\Iris\Message 对象。

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');

在所有其他操作之前，您可能想要指定自己的用户代理。默认情况下，库会设置自己的用户代理。您可以通过使用 P\Iris\Message::setUserAgent 方法来覆盖此行为。一旦设置，用户代理就不会改变，即使您重置了 Iris\Message 对象。

在任何时候，您都可以重置当前的 cURL 处理程序，这样您就可以使用相同的 P\Iris\Message 对象执行多个调用。一旦重置，对象将失去对旧请求的任何引用，除了用户代理和 附加到它的监听器 之外。

$request->reset();

添加选项

cURL 调用全部都是关于选项的，P\Iris\Message 帮助您使用 setOption 方法设置它们。

setOption 方法可以接受一个 array 作为单个值或 cURL 选项及其值。

$request->setOption(CURLOPT_NOBODY, true);
//or
$request->setOption([
    CURLOPT_NOBODY => true,
    CURLOPT_HEADER_OUT => true
]);

在执行请求之前，可以更改和修改选项，因为它们仅在执行请求时应用。

执行请求

使用过程化代码

要执行请求，您需要调用 Iris\Message::execute 方法。

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');
$request->setOption(CURLOPT_URL, 'http://www.example.com');
$request->setOption(CURLOPT_RETURNTRANSFER, true);
$request->execute();
if ($request->getErrorCode()) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
} else {
    $status = $request->getInfo(CURLOPTINFO_HTTP_CODE); //return the Status Code
    echo $request->getResponse();
}

您将可以通过以下方式访问：

• 使用 P\Iris\Message::getResponse 方法获取响应。
• 使用 P\Iris\Message::getInfo 方法获取 cURL 请求信息。此方法默认返回所有可用信息的数组。如果您只对某个值感兴趣，请使用它的 CURLINFO_* 索引；
• 通过 P\Iris\Message::getErrorCode 和 P\Iris\Message::getErrorMessage 方法访问 cURL 错误；

使用事件

处理结果的另一种方法是使用事件监听器。`\Iris\Message` 包含一个简单的事件监听器机制。您可以注册任意数量的回调函数，它们将在请求成功或请求错误时执行，如下所述

$request = new Message;
$request->setUserAgent('My beautiful user agent/1.0');
$request->setOption(CURLOPT_URL, 'http://www.example.com');
$request->setOption(CURLOPT_RETURNTRANSFER, true);
$request->addListener(Message::EVENT_ON_SUCCESS, function ($res, $curl) {
    echo $curl->getInfo(CURLOPTINFO_HTTP_CODE); //return the Status Code
});
$request->addListener(Message::EVENT_ON_FAIL, function ($res, $curl) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
});
$request->execute();

根据 cURL 请求的结果，将调用其中一个事件。当然，您可以使用与添加回调时相同的参数，通过 P\Iris\Message::removeListener 来移除回调。

简单请求（GET、POST、PUT、DELETE、HEAD）

该类提供专门的方法来执行REST API中常用的调用

• P\Iris\Message::get 用于发出 GET 请求；
• P\Iris\Message::post 用于发出 POST 请求；
• P\Iris\Message::put 用于发出 PUT 请求；
• P\Iris\Message::delete 用于发出 DELETE 请求；
• P\Iris\Message::head 用于发出 HEAD 请求；

这些方法最多接受3个参数

• 第一个参数是要请求的URL；
• 第二个参数可以是数组、可遍历对象或字符串。这是将用于URL的数据；
• 第三个参数用于指示是否延迟请求。默认情况下，请求不会延迟，其值为 false（即：与 P\Iris\Batch 结合使用时很有用）；

以下是一个简单的示例

$request = new Message;
$request->addListener(Message::EVENT_ON_SUCCESS, function ($res, $curl) {
    echo $request->getResponse();
});
$request->addListener(Message::EVENT_ON_FAIL, function ($res, $curl) {
    echo $curl->getErrorCode().': '. $curl->getErrorMessage();
});
$request->get(
    'http://www.example.com/path/to/my/script',
    ['var1' => 'value2',   ...]
);

您不需要使用 P\Iris\Message::execute 方法，因为它会直接由 P\Iris\Message::get 方法调用。如果您不想直接发出请求，则必须使用 第三个参数 来指定它。

$request = new Message;
$request->get(
    'http://www.example.com/path/to/my/script',
    json_encode(['var1' => 'value2', ...]),
    true
);
$request->execute();
echo $request->getResponse();

请求已注册但未执行，您需要显式调用 P\Iris\Message::execute 或 P\Iris\Batch::execute 来执行请求。

Iris\Envelope

此类负责包装 curl_multi_* 函数。 因为它可以用于使用 cURL 执行并行调用，但实际应用中不这样做，使用 P\Iris\Batch 有更简单的方法。

此函数的唯一目的是配置在并行请求中使用 cURL 时 cURL 的行为。您可以指定

• 要执行的最大并行请求数量。默认情况下，此数字为 10，但您可以使用 setOption 方法更改此数字，就像使用 P\Iris\Message 类一样 注意：

  • 在 PHP 5.5 之前无法设置选项。
  • 该类包含一个常量，名为 P\Iris\Envelope::MAXCONNECTS，其值与PHP5.5+ 常量 CURLMOPT_MAXCONNECTS 的值相同，因此这两个常量可以互换使用。

• 用于设置 selectTimeout 和 execTimeout，这两个值由 cURL 用于执行请求。这些值可以通过简单的获取器和设置器方法进行设置和获取。

  • selectTimeout 必须是一个浮点数；
  • execTimeout 必须是一个整数；

Iris\Batch

实例化

该类是为了简化并行调用而构建的。要实例化此类，您必须给它一个 Iris\Enveloppe 类型的对象。

<?php
use P\Iris\Envelope;
use P\Iris\Batch;

$envelope = new Envelope;
$envelope->setSelectTimeout(10.00);
$evenlope->setExecTimeout(100);
$envelope->setOption(Envelope::MAXCONNECTS, 3);
$batch = new Batch($enveloppe);

添加请求

一旦实例化 \P\Iris\Batch，只需提供要并行执行的 cURL 请求。

为此，您可以使用 \P\Iris\Batch::addOne 函数，该函数将添加一个单个的 \P\Iris\Message 对象，或者使用 \P\Iris\Batch::addMany，它将接受一个包含仅 \P\Iris\Message 对象的 array 或任何 Traversable 对象。

$batch->addOne($request);
//or
$batch->addMany([$request1, $request2]);

在任何给定时间，您都可以计算 \P\Iris\Batch 对象中存在的 \P\Iris\Message 对象的数量。随着对象执行请求，此数字将减少。

$nb_messages = count($batch);

执行请求

$batch->execute();

一旦添加了所有 \P\Iris\Message 对象，您就可以安全地使用 \P\Iris\Batch::execute 方法执行并行请求。

当使用 \P\Iris\Batch 时，您必须使用 \P\Iris\Message 事件监听器来分别处理每个 cURL 请求。

贡献

有关详细信息，请参阅 CONTRIBUTING。

鸣谢

• ignace nyamagana butera
• bertrand andres