README

一个设计用于与 ATK14 restful API 通信的客户端库。它也适用于其他 JSON API。

基本用法

$adf = new ApiDataFetcher("https://skelet.atk14.net/api/");

$data = $adf->get("articles/detail",["id" => 123]);
// or
$data = $adf->get("articles/detail/?id=123");

$title = $data["title"];

实际上，在这个例子中，我们向 URL https://skelet.atk14.net/api/en/articles/detail/?id=123&format=json 发起了 HTTP GET 请求，并返回了解码后的 JSON 数据。

可以这样进行 POST 请求

$data = $adf->post("articles/create_new",[
  "title" => "Brand New Article",
  "body" => "Once upon a time..."
]);
// or
$data = $adf->post("articles/create_new/?title=Brand+New+Article&body=Once+upon+a+time...");

参数格式=json 会自动添加到每个请求中。这是 ATK14 API 中的惯例。可以通过在构造函数中设置选项来禁用此行为。

为了完整起见，还有 put 和 delete 方法。

$data = $adf->put("articles",[
  "title" => "Brand New Article",
  "body" => "Once upon a time..."
]);
// or
$data = $adf->put("articles/?title=Brand+New+Article&body=Once+upon+a+time...");

$data = $adf->delete("article",["id" => 123]);
// or
$data = $adf->delete("article/?id=123");

用于上传文件的函数

$data = $adf->postFile("images/create_new","/path/to/image.jpg",["title" => "Beautiful Flower", "description" => "..."]);
// or
$file_specs = [
  "path" => "/path/to/file",
  "postname" => "image",
  "name" => "flower.jpg",
  "mime_type" => "image/jpeg",
];
$data = $adf->postFile("images/create_new",$file_specs,["title" => "Beautiful Flower", "description" => "..."]);

用于发送 JSON 的便捷方法

$params = ["param1" => "val1", "param2" => "val2"];
$json = json_encode($params);

$data = $adf->postJson("endpoint",$json);
// or
$data = $adf->postJson("endpoint",$params);

处理错误代码

默认情况下，ApiDataFetcher 在收到非 2XX 响应代码时会抛出异常。为了在 API 方法中处理有效的错误代码，请指定这些代码到选项 acceptable_error_codes 中。

$data = $adf->post("logins/create_new",[
  "login" => "johny.long",
  "password" => "JulieIsNoMore"
],[
  "acceptable_error_codes" => [
    401, // Unauthorized: Bad password
    404, // Not Found: There is no such user
  ]
]);

if(!$data){
  if($adf->getStatusCode()==401){
     // Bad password
  }
  if($adf->getStatusCode()==404){
     // There is no such user
  }
}

语言

ApiDataFetcher 会尝试自动检测运行中的应用程序中当前使用的语言，并在 API 方法调用中使用它。

语言也可以在构造函数或特定的 API 方法调用中指定。

$adf = new ApiDataFetcher("https://skelet.atk14.net/api/",["lang" => "en"]);

$data_in_english = $adf->get("articles/detail",["id" => 123]); // performs call to https://skelet.atk14.net/api/en/articles/detail/?id=123&format=json

$data_in_czech = $adf->get("articles/detail",["id" => 123],["lang" => "cs"]); // performs call to https://skelet.atk14.net/api/cs/articles/detail/?id=123&format=json

对于非 ATK14 API，您可能希望禁用考虑所有语言。

$adf = new ApiDataFetcher("http://somewhere-on-the.net/json-api/",["lang" => ""]);

$data = $adf->get("articles",["id" => 123]);

HTTP Basic 认证

API 是否需要基本认证？ApiDataFetcher 没问题！

$adf = new ApiDataFetcher("https://username:password@api-on-the.net/api/");

缓存

$adf->get("articles/index",["year" => "100"],["cache" => 600]); // caching fetched content for 10 minutes (600 seconds)

// use expired cached content when an error occurs
$adf->get("articles/index",["year" => "100"],[
  "cache" => 600,
  "return_cached_content_on_error" => true
]); 

Tracy 面板集成

ApiDataFetcher 包附带 ApiDataFetcherPanel，以便轻松集成到流行的调试器 Tracy (https://packagist.org.cn/packages/tracy/tracy)

$tracy_bar = Tracy\Debugger::getBar();
$tracy_bar->addPanel(new ApiDataFetcherPanel($api_data_fetcher));

安装

使用 Composer 安装 ApiDataFetcher。

cd path/to/your/atk14/project/
composer require atk14/api-data-fetcher

在项目配置文件中，可以定义常量 API_DATA_FETCHER_BASE_URL。

define("API_DATA_FETCHER_BASE_URL","https://skelet.atk14.net/api/");

许可

ApiDataFetcher 是在 MIT 许可证下免费软件，具体条款请参阅MIT 许可证