README

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

安装

需要PHP 7.2或更高版本。对于PHP的旧版本，使用0.1.7。

$ composer 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"
]);

-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 (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"]
]);

-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

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

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

tcdent / php-restclient

维护者

详细信息