README

RestAgent 是一个用于 PHP 的 HTTP/HTTPS 客户端库。项目的主要目标是：

提供优雅直观的 API。
正确支持 HTTPS。
最小化模板代码，让使用 PHP 处理 HTTP(S) 更加愉快。
提供丰富的功能集以支持 RESTful 交互。

RestAgent 的 API 吸取了 Node.js 的 SuperAgent 库的 API 简洁性，该库由 TJ Holowaychuk 开发，可在 https://github.com/visionmedia/superagent 找到。

兼容性

PHP 5.3 或更高版本。

安装

1. 安装 Composer

$ curl -sS https://getcomposer.org/installer | php
$ sudo mv composer.phar /usr/local/bin/composer
$ composer -v

或者查看详细文档： https://getcomposer.org/doc/00-intro.md

2. 在项目中包含 RestAgent

在您的 composer.json 中添加 inadarei/restagent。

{
  "require": {
    "inadarei/restagent": "^2.0.0"
  }
}

运行: composer install

安装后，您需要在项目文件中引入 Composer 的自动加载器，如果您尚未这样做的话

require_once './vendor/autoload.php';

快速文档

发送请求

发送简单的 HTTP GET 请求

$request = new \Restagent\Request;

$response = $request->get("http://example.com/user/1");

设置请求的基本 URL

$request = new \Restagent\Request('http://restagent.vm:8080/api/');

$response = $request->get("/user/1");

有点戏剧性，请看下面

$response = $request->header('Content-Type', 'application/json')
                    ->header("X-API-Key", "aabbccdd")
                    ->get("http://example.com/user/1");

组装并发送 HTTP POST 请求

$response = $request
                ->header("X-API-Key", "aabbccdd")
                ->data(array("firstName" => "Irakli", "lastName" => "Nadareishvili"))
                ->data("hobby", "programming")
                ->header(array("User-Agent" => "RestAgent/1.0 php/libcurl", "foo" => "bar"))
                ->param("active", 1)
                ->post("http://example.com/user");

在 HTTP BODY 中包含原始数据的 HTTP PUT 请求

$json = '{"name" : "irakli", "lastname" : "nadareishvili"}';
$response = $request
                ->header("X-API-Key", "aabbccdd")
                ->body($json)
                ->header(array("User-Agent" => "RestAgent/1.0 php/libcurl", "foo" => "bar"))
                ->put("http://example.com/user");

使用自定义 HTTP 方法并设置自定义超时时间

$response = $request
                ->data(array("firstName" => "Irakli", "lastName" => "Nadareishvili"))
                ->header("X-API-Key", "aabbccdd")
                ->header(array("User-Agent" => "CERN-LineMode/2.15 libwww/2.17b3"))
                ->method("PATCH")
                ->timeout(500)
                ->send("/user/1");

在哪里

header() 设置 HTTP 头部
data() 设置在请求过程中传递的数据变量。在 HTTP GET 的情况下，它可以是查询参数；在 HTTP POST、PUT 等情况下，它可以是 HTTP 主体中的变量。
param() 允许在非 HTTP GET 调用中设置查询参数（即当 data() 会设置请求体中的变量而不是 URL 时）。注意：不要在 HTTP GET 中使用 param()，否则您将收到异常。请使用 data() 代替！更多内容请见下文。
head(), get(), post(), put() 和 delete() 调用会发送相应的 HTTP 请求。
method() 设置与 send() 调用一起使用的自定义 HTTP 方法。
timeout() 覆盖默认超时为指定的毫秒数。

请注意，data(), param() 和 header() 方法可以接受数组或单个名称/值对作为参数。为什么？因为根据不同情况，它们都可能是方便的。

此外，像 ->get() 和 ->post() 这样的方法只是调用 ->method("get")->send(...) 的便利快捷方式。如果您想使用上述列表中未包含的任何 HTTP 方法，请尝试发出 ->method(...)->send();

为什么 param() 又出现了？

param() 方法的目的是令人困惑的，可能需要进一步的解释。

在纯粹 RESTful 的观点中，我们希望有一种统一的方式来进行 HTTP 调用并传递变量，就像我们做的那样。因此，作为一条一般规则，能够使用统一的 data() 方法设置请求数据非常重要。之后，我们可以进行适当的 HTTP-verb 调用（无论是 GET、PUT 还是其他什么），而不用担心动词如何编码数据（在 URL 中或 HTTP 主体中）的细节。

话虽如此，有时我们确实需要在HTTP调用中添加HTTP查询参数，即使这些调用在HTTP体中编码了变量（例如POST或PUT）。无论我们是否认为它是RESTful的，在HTTP中都是允许的，有时甚至可能是一种必要的“邪恶”。这就是为什么存在param()的原因：允许此类用例。

然而，我们不允许在HTTP GET中使用param()，因为data()方法已经做了param()会做的事情，如果有人决定通过param()和data()同时设置相同的变量，那么就会产生混淆，决定哪种方法具有优先级或者变量如何合并。

这就是为什么在HTTP GET调用中使用param()会导致异常，这个异常基本上表明：“我们给你提供了一个在POST、PUT等操作中快捷系统的方法，现在不要那么愚蠢，不要试图在GET中用它，因为你真的不应该用它”。

这就是param()及其与data()之间关系的漫长故事...

响应格式

head()、get()、post()、put()、delete()和send()调用返回一个关联数组，具有以下结构

code: HTTP响应代码。
meta: 来自CURL的关于调用的大量元信息。
data: 除HTTP HEAD之外任何HTTP方法的响应内容。根据定义，后者不返回任何内容，因此'data'包含解析后的HTTP响应头。

CURL调试

通过设置REST_AGENT_DEBUG（实际上可以是任何值）

export REST_AGENT_DEBUG=true

您可以使用CURL调试。

许可证

（MIT许可证）

以下条件下，任何人都可以免费获得本软件及其相关文档副本（“软件”），不受限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许获得软件的人这样做，前提是

inadarei / restagent

维护者

详情