README

原始包（UNIREST）似乎已被遗弃。我们将尝试在这里保持其更新。

Unirest 是一套轻量级的 HTTP 库，支持多种语言，由 Mashape 构建，并维护开源 API 网关 Kong。

特性

• 提供调用 GET、HEAD、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE、PATCH 请求的实用方法
• 支持表单参数、文件上传和自定义体实体
• 支持 gzip
• 原生支持 Basic、Digest、Negotiate、NTLM 身份验证
• 可自定义超时时间
• 可自定义每个请求的默认头信息（DRY）
• 自动将 JSON 响应解析为原生对象

要求

• cURL
• PHP 5.4+

安装

使用 Composer

要使用 Composer 安装 restuni-php，只需将以下内容添加到您的 composer.json 文件中

{
    "require-dev": {
        "braghim-sistemas/restuni-php": "^7"
    }
}

或运行以下命令

composer require braghim-sistemas/restuni-php ^7

这将获取最新版本的包并将其安装。如果您想要 master 分支的未标记版本，可以使用以下命令

composer require braghimsistemas/php-test-reporter dev-master

Composer 在 ./vendor/autoloader.php 处安装自动加载器。要将库包含到您的脚本中，请添加

require_once 'vendor/autoload.php';

如果您使用 Symfony2，自动加载器需要自动检测。

您可以在 Packagist 上看到这个库。

从源代码安装

从 Github 下载 PHP 库，然后在您的脚本中包含 Unirest.php

git clone git@github.com:Mashape/restuni-php.git

require_once '/path/to/restuni-php/src/Unirest.php';

用法

创建请求

您可能想知道如何使用 Unirest 让 PHP 中的请求创建变得更简单，以下是一个示例

$headers = array('Accept' => 'application/json');
$query = array('foo' => 'hello', 'bar' => 'world');

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $query);

$response->code;        // HTTP Status code
$response->headers;     // Headers
$response->body;        // Parsed body
$response->raw_body;    // Unparsed body

JSON 请求 (application/json)

可以使用 Unirest\Request\Body::Json 辅助器构建 JSON 请求

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'braghimsistemas');

$body = Unirest\Request\Body::json($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

注意

• Content-Type 头部将自动设置为 application/json
• 数据变量将通过 json_encode 进行处理，使用默认参数值。
• 如果未安装 JSON 扩展，将抛出错误。

表单请求 (application/x-www-form-urlencoded)

可以使用 Unirest\Request\Body::Form 辅助器构建典型的表单请求

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'braghimsistemas');

$body = Unirest\Request\Body::form($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

注意

• Content-Type 头部将自动设置为 application/x-www-form-urlencoded
• 最终的数据数组将通过 http_build_query 进行处理，使用默认参数值。

多部分请求 (multipart/form-data)

可以使用 Unirest\Request\Body::Multipart 辅助器构建多部分请求

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'braghimsistemas');

$body = Unirest\Request\Body::multipart($data);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

注意

• Content-Type 头部将自动设置为 multipart/form-data。
• 将设置自动生成的 --boundary。

多部分文件上传

只需将文件数组作为 Multipart 辅助器的第二个参数添加即可

$headers = array('Accept' => 'application/json');
$data = array('name' => 'ahmad', 'company' => 'braghimsistemas');
$files = array('bio' => '/path/to/bio.txt', 'avatar' => '/path/to/avatar.jpg');

$body = Unirest\Request\Body::multipart($data, $files);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

如果您希望进一步自定义上传文件的属性，可以使用 Unirest\Request\Body::File 辅助器

$headers = array('Accept' => 'application/json');
$body = array(
    'name' => 'ahmad',
    'company' => 'braghimsistemas'
    'bio' => Unirest\Request\Body::file('/path/to/bio.txt', 'text/plain'),
    'avatar' => Unirest\Request\Body::file('/path/to/my_avatar.jpg', 'text/plain', 'avatar.jpg')
);

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

注意：在此示例中我们没有使用 Unirest\Request\Body::multipart 辅助器，在手动添加文件时不需要。

自定义体

发送自定义正文而不是使用 Unirest\Request\Body 辅助器也是可能的，例如，使用带有自定义 Content-Type 的 serialize 正文字符串

$headers = array('Accept' => 'application/json', 'Content-Type' => 'application/x-php-serialized');
$body = serialize((array('foo' => 'hello', 'bar' => 'world'));

$response = Unirest\Request::post('http://mockbin.com/request', $headers, $body);

身份验证

首先，如果您正在使用 [Mashape][braghimsistemas-url]

// Mashape auth
Unirest\Request::setMashapeKey('<braghimsistemas_key>');

否则，传递用户名、密码 (可选)，默认为基本身份验证

// basic auth
Unirest\Request::auth('username', 'password');

第三个参数，它是一个位掩码，将告诉 Unirest 您希望它为您的代理身份验证使用哪种 HTTP 身份验证方法。

如果设置了多个位，Unirest (在 PHP 的 libcurl 级别) 将首先查询网站以查看它支持哪些身份验证方法，然后选择您允许它使用的最佳方法。 对于某些方法，这可能会导致额外的网络往返。

支持的方法

// custom auth method
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);

Unirest 的早期版本通过提供 username 和 password 参数来支持 基本身份验证

$response = Unirest\Request::get('http://mockbin.com/request', null, null, 'username', 'password');

这已被弃用，将在 v.3.0.0 中完全删除，请使用 Unirest\Request::auth() 方法代替

Cookie

设置一个 cookie 字符串以指定 cookie 标头的内容。多个 cookie 用分号加空格分隔（例如，"fruit=apple; colour=red"）

Unirest\Request::cookie($cookie)

设置一个 cookie 文件路径以启用 cookie 读取并在多个请求序列中存储 cookie。

Unirest\Request::cookieFile($cookieFile)

$cookieFile 必须是一个正确的路径，并且具有写入权限。

请求对象

Unirest\Request::get($url, $headers = array(), $parameters = null)
Unirest\Request::post($url, $headers = array(), $body = null)
Unirest\Request::put($url, $headers = array(), $body = null)
Unirest\Request::patch($url, $headers = array(), $body = null)
Unirest\Request::delete($url, $headers = array(), $body = null)

• url - 要执行操作并请求信息的端点、地址或 URI。
• headers - 请求头作为关联数组或对象。
• body - 请求体作为关联数组或对象。

您可以使用任何 标准 或自定义 HTTP 方法发送请求。

Unirest\Request::send(Unirest\Method::LINK, $url, $headers = array(), $body);

Unirest\Request::send('CHECKOUT', $url, $headers = array(), $body);

响应对象

接收到响应后，Unirest 以对象的形式返回结果，该对象应始终具有与响应详细信息相关的相同键。

• code - HTTP 响应状态码（例如 200）
• headers - HTTP 响应头
• body - 适用于解析响应体的关联数组或对象，例如 JSON 响应被解析为对象/关联数组。
• raw_body - 未解析的响应体

高级配置

您可以设置一些高级配置来调整 Unirest-PHP

自定义 JSON 解码标志

Unirest 使用 PHP 的 JSON 扩展 自动解码 JSON 响应。有时您可能希望返回关联数组、限制递归深度或使用任何 自定义标志。

要这样做，只需使用 jsonOpts 请求方法设置所需的选项即可

Unirest\Request::jsonOpts(true, 512, JSON_NUMERIC_CHECK & JSON_FORCE_OBJECT & JSON_UNESCAPED_SLASHES);

超时

您可以设置一个自定义的超时值（以 秒 为单位）

Unirest\Request::timeout(5); // 5s timeout

代理

设置用于即将到来的请求的代理。

您还可以设置代理类型为以下之一：CURLPROXY_HTTP、CURLPROXY_HTTP_1_0、CURLPROXY_SOCKS4、CURLPROXY_SOCKS5、CURLPROXY_SOCKS4A 和 CURLPROXY_SOCKS5_HOSTNAME。

请参阅 cURL 文档 以获取更多信息.

// quick setup with default port: 1080
Unirest\Request::proxy('10.10.10.1');

// custom port and proxy type
Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP);

// enable tunneling
Unirest\Request::proxy('10.10.10.1', 8080, CURLPROXY_HTTP, true);

代理身份验证

传递用户名、密码 (可选)，默认为基本身份验证

// basic auth
Unirest\Request::proxyAuth('username', 'password');

第三个参数，它是一个位掩码，将告诉 Unirest 您希望它为您的代理身份验证使用哪种 HTTP 身份验证方法。

如果设置了多个位，Unirest (在 PHP 的 libcurl 级别) 将首先查询网站以查看它支持哪些身份验证方法，然后选择您允许它使用的最佳方法。 对于某些方法，这可能会导致额外的网络往返。

有关支持的方法的详细信息，请参阅 身份验证

// basic auth
Unirest\Request::proxyAuth('username', 'password', CURLAUTH_DIGEST);

默认请求头

您可以设置将在每次请求中发送的默认头

Unirest\Request::defaultHeader('Header1', 'Value1');
Unirest\Request::defaultHeader('Header2', 'Value2');

您可以通过传递一个数组来批量设置默认头

Unirest\Request::defaultHeaders(array(
    'Header1' => 'Value1',
    'Header2' => 'Value2'
));

您可以通过以下方式随时清除默认头

Unirest\Request::clearDefaultHeaders();

默认 cURL 选项

您可以为每次请求设置默认的cURL选项

Unirest\Request::curlOpt(CURLOPT_COOKIE, 'foo=bar');

您可以通过传递一个数组来批量设置选项

Unirest\Request::curlOpts(array(
    CURLOPT_COOKIE => 'foo=bar'
));

您可以使用以下方法随时清除默认选项

Unirest\Request::clearCurlOpts();

SSL验证

当消费受SSL保护的端点时，您可以显式启用或禁用SSL证书验证

Unirest\Request::verifyPeer(false); // Disables SSL cert validation

默认情况下是true。

实用方法

// alias for `curl_getinfo`
Unirest\Request::getInfo()

// returns internal cURL handle
Unirest\Request::getCurlHandle()