README

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

https://github.com/kredeum/php-restclient
2021 Kredeum contact@kredeum.com

安装

$ php composer.phar require kredeum/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的字符串或关联数组，在所有其他请求中作为请求正文传递。如果传递数组，则将其编码为查询字符串。传递嵌套、索引的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>

多部分添加（Kredeum）

向php-restclient添加多部分功能

   * function multipart($parts, $boundary)
   *
   * parts = array of $part
   * $part['type'] = 'text' || "file" || "json" || "html"
   * $part['name']
   * $part['content']
   * $part['headers']
   *
   * $boundary = whatever string to separate parts
   *
   * returns parts encoded

kredeum / php-restclient

维护者

详细信息