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

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

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团队用心制作