README

https://github.com/tcdent/php-restclient
(c) 2013-2017 Travis Dent tcdent@gmail.com

安装

$ composer require brycegough/php-restclient

基本用法

$api = new RestClient([
    'base_url' => "https://api.twitter.com/1.1",
    'format' => "json",
     // https://dev.twitter.com/docs/auth/application-only-auth
    'headers' => ['Authorization' => 'Bearer '.OAUTH_BEARER],
]);
$result = $api->get("search/tweets", ['q' => "#php"]);
// GET http://api.twitter.com/1.1/search/tweets.json?q=%23php
if($result->info->http_code == 200)
    var_dump($result->decode_response());

可配置选项

headers - 每个请求中包含的HTTP头和值的关联数组。
parameters - 每个请求中包含的URL或正文参数的关联数组。
curl_options - 应用到每个请求的cURL选项；这里定义的任何内容：https://secure.php.net/manual/en/function.curl-setopt.php。这些将覆盖任何自动生成的值。
build_indexed_queries (bool) - http_build_query 自动为重复参数添加数组索引，这在大多数系统中是不希望的。使用此选项启用默认行为。默认为 FALSE。 user_agent - 请求中使用的用户代理字符串。
base_url - 用于每个请求基础的URL。
format - 格式字符串附加到请求资源（扩展）上，并在响应中用于确定使用哪个解码器；一个请求URL如 "api.twitter.com/1.1/statuses/user_timeline.json" 应返回格式良好的JSON。
format_regex - 从响应Content-Type头中提取格式的模式，用于确定响应中使用的解码器。
decoders - 格式解码器的关联数组。见"直接迭代和响应解码"。
username - 用于HTTP基本认证的用户名。需要 password。
password - 用于HTTP基本认证的密码。需要 username。

选项可以在实例化时设置，也可以在之后单独设置

$api = new RestClient([
    'format' => "json",
    'user_agent' => "my-application/0.1"
]);

-或-

$api = new RestClient;
$api->set_option('format', "json");
$api->set_option('user_agent', "my-application/0.1");

标准动词

实现了四个HTTP动词作为便捷方法：get()、post()、put()和delete()。每个都接受三个参数

url (string) - 你请求的资源URL。如果已配置，将添加到base_url选项。如果已配置，将添加到format选项。

parameters (string), (array) - 要附加到URL的字符串或关联数组，在GET请求中附加，并在所有其他请求中传递给请求体。如果传递数组，它将编码为查询字符串。一个嵌套的、索引的array传递给具有多个值的参数，并将迭代以填充重复键。见"重复头和参数"

headers (array) - 要包含在请求中的头部的关联数组。一个嵌套的、索引的array传递给具有多个值的参数，并将迭代以填充重复键。见"重复头和参数"

其他动词

你可以通过直接调用execute()来使用任何动词发出请求，该函数接受四个参数：url、method、parameters和headers。所有参数都期望与便捷方法中的相同值，除了额外的method参数。

method (string) - 执行请求的HTTP动词。

响应细节

在用HTTP动词方法之一或execute发起请求后，返回的实例将填充以下数据

response (字符串) - 原始响应体内容。有关解析和访问此数据的说明，请参阅"直接迭代和响应解码"。

headers (对象) - 包含所有响应头部的对象。索引被转换为snake_case以便访问。重复的头部作为共享键下的索引数组可用。

$response->headers->content_type;
$response->headers->x_powered_by;

info (对象) - 包含事务信息的对象。通过将curl_info转换为对象进行填充。有关更多信息，请参阅PHP文档：https://php.ac.cn/manual/en/function.curl-getinfo.php 可用的属性包括

url, content_type, http_code, header_size, request_size, filetime,
ssl_verify_result, redirect_count, total_time, namelookup_time, connect_time,
pretransfer_time, size_upload, size_download, speed_download, speed_upload,
download_content_length, upload_content_length, starttransfer_time, redirect_time,
certinfo, primary_ip, primary_port, local_ip, local_port, redirect_url  

error (字符串) - cURL错误消息（如果适用）。

response_status_lines (数组) - 原始HTTP响应状态行的索引数组。请参阅："多重HTTP状态行"。

直接迭代和响应解码

如果响应数据格式受支持，响应将被解码，并可通过迭代返回的实例来访问。当设置了format选项时，它将用于选择解码器。如果没有提供format选项，将尝试从响应的Content-Type头部提取它。此模式可通过format_regex选项进行配置。

$api = new RestClient([
    'base_url' => "http://vimeo.com/api/v2",
    'format' => "php"
]);
$result = $api->get("tcdent/info");
// GET http://vimeo.com/api/v2/tcdent/info.php
foreach($result as $key => $value)
    var_dump($value);

也实现了通过ArrayAccess进行读取

var_dump($result['id']);

要访问解码的响应作为数组，请调用decode_response()。

'json'和'php'格式配置为分别使用内置的json_decode和unserialize函数。在实例化时可以指定覆盖和额外的解码器，或者在之后单独指定。解码函数接受一个参数：原始请求数据。使用create_function创建的lambda函数和函数也适用。

function my_xml_decoder($data){
    new SimpleXMLElement($data);
}

$api = new RestClient([
    'format' => "xml",
    'decoders' => ['xml' => "my_xml_decoder"]
]);

-或-

$api = new RestClient;
$api->set_option('format', "xml");
$api->register_decoder('xml', "my_xml_decoder");

或者，使用lambda函数；这个特定的例子允许你以数组形式接收解码后的JSON数据。

$api->register_decoder('json', function($data){
    return json_decode($data, TRUE);
});

重复的头部和参数

当收到重复（重复）的HTTP头部时，它们可以通过共享键引用的索引数组访问。重复的头部和参数也可以使用相同的格式在请求中构建。

示例（不太可能）响应

HTTP/1.1 200 OK
Content-Type: text/html
Content-Type: text/html; charset=UTF-8

在响应实例中访问重复的头部

$result = $api->get('/');
var_dump($result->headers->content_type);

=> ["text/html", "text/html; charset=UTF-8"]

在请求中传递重复的头部和参数

$result = $api->get('/', [
    'foo[]' => ['bar', 'baz']
], [
    'Accept' => ['text/json', 'application/json']
]);

将创建以下内容的头部和一个查询字符串（GET）或响应体（POST等）

GET /?foo[]=bar&foo[]=baz HTTP/1.1
Accept: text/json
Accept: application/json

多重HTTP状态行

支持在单个响应负载中返回多个状态行，并且作为response_status_lines提供，它是一个填充在响应实例上的索引数组。

包含多个状态行的示例响应（已截断）

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Cache-Control: no-cache
...

$result = $api->get('/');
var_dump($result->response_status_lines);

=> ["HTTP/1.1 100 Continue", "HTTP/1.1 200 OK"]

JSON动词

此库永远不会验证或构建PATCH JSON内容，但它可以配置为通信良好格式的数据。

具有正确内容类型的PATCH JSON内容

$result = $api->execute("http://httpbin.org/patch", 'PATCH',
    json_encode([foo' => 'bar']), [
        'X-HTTP-Method-Override' => 'PATCH',
        'Content-Type' => 'application/json-patch+json']);

测试

测试包包括一个简单的服务器脚本，该脚本返回用于验证功能的调试信息。首先启动服务器，然后运行测试

$ php -S localhost:8888 test.php
$ phpunit test

• 需要PHP > 5.5.7才能填充getallheaders数据。
• 如果您指定了PHP服务器的备用端口号或主机名，您需要在phpunit.xml文件中重新配置它

<php><var name="TEST_SERVER_URL" value="https://:8888"/></php>