README

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

安装

$ php composer.phar require tcdent/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 - 格式字符串附加到请求的资源上（扩展），并用于确定响应上使用的解码器；一个像"api.twitter.com/1.1/statuses/user_timeline.json"这样的请求URL应返回格式良好的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 (string) - 原始响应体内容。有关解析和访问此数据的详细信息，请参阅"直接迭代和响应解码"。

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

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

info (object) - 包含交易信息的对象。通过将 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 (string) - cURL错误消息（如果适用）。

response_status_lines (array) - 原始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 函数。可以在实例化时指定覆盖和额外的解码器，或者在之后单独指定。解码器函数接受一个参数：原始请求体。Lambdas 和使用 create_function 创建的函数也有效。

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

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

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