README

(https://packagist.org.cn/packages/ggeweb/php-restclient)

https://github.com/ggeweb/php-restclient
由Travis Dent创建（c）2013-2022 tcdent@gmail.com，由Marcos Souza Filho@msfilho分支和修改

安装

需要PHP 7.2或更高版本。

$ composer require ggeweb/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?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。
format_regex - 从响应Content-Type头中提取格式的模式，用于确定在响应上使用哪个解码器。
decoders - 格式解码器的关联数组。请参阅"直接迭代和响应解码"。
username - 用于HTTP基本认证的用户名。需要password。
password - 用于HTTP基本认证的密码。需要username。

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

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

-or-

$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的字符串或关联数组，在所有其他请求中将传递请求体。如果传递数组，则将其编码为查询字符串。对于具有多个值的参数，传递嵌套、索引的array，将迭代以填充重复的键。请参阅"重复头和参数"

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

其他动词

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

method (字符串) - 执行请求的 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("demo/info");
// GET http://vimeo.com/api/v2/demo/info
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"]
]);

-or-

$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 RestClientTest.php
$ phpunit RestClientTest

• 需要 PHP > 5.5.7，以便填充 getallheaders 数据。
• 如果您指定了 PHP 服务器的外部端口号或主机名，则需要重新配置您的 phpunit.xml 文件。

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