README

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

功能

• 提供调用 GET、HEAD、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE、PATCH 请求的实用方法
• 支持表单参数、文件上传和自定义主体实体
• 支持 gzip
• 原生支持基本、摘要、协商、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 辅助函数也是可能的，例如，使用一个自定义的 serialize 正文字符串和一个自定义的 Content-Type

$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团队用心打造