README

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 安装 unirest-php，只需将以下内容添加到您的 composer.json 文件中

{
    "require-dev": {
        "mashape/unirest-php": "3.*"
    }
}

或者运行以下命令

composer require mashape/unirest-php

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

composer require mashape/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/unirest-php.git 

require_once '/path/to/unirest-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' => 'mashape');

$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' => 'mashape');

$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' => 'mashape');

$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' => 'mashape');
$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' => 'mashape'
    '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

// Mashape auth
Unirest\Request::setMashapeKey('<mashape_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()

由Mashape团队制作