README

APIZ 是一个 PHP API 客户端开发套件，它可以帮助您以面向对象的方式管理 HTTP API 调用。您可以使用此包轻松处理和隔离所有类型的 REST API 调用及其响应。

要求

PHP >= 5.5.9

安装

composer require nahid/apiz

配置

此包没有额外的配置。

使用方法

让我们看看一个从 https://reqres.in 消费 API 的例子。

假设您需要为您项目创建几个 API 服务。您的服务目录是 app/Services。现在我们正在为 https://reqres.in 开发一个服务，并创建一个名为 ReqResApiService.php 的类文件，它将扩展 \Apiz\AbstractApi 类。

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }
}

getBaseURL() 是 AbstractApi 类的一个抽象方法。您需要重写此方法以设置 API 的正确基本 URL。

一些 API 在它们的 URL 中有一个共同的前缀。例如，这里 reqres.in 在每个端点都有一个前缀 api。因此，我们将重写 getPrefix() 方法来定义前缀。

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }

    protected function getPrefix()
    {
        return 'api';
    }
}

现在让我们创建一个获取所有用户信息的方法。

namespace App\Services;

use Apiz\AbstractApi;

class ReqResApiService extends AbstractApi
{
    protected function getBaseURL()
    {
        return 'https://reqres.in';
    }

    protected function getPrefix()
    {
        return 'api';
    }

    public function getAllUsers()
    {
        $response = $this->get('users');

        if ($response->getStatusCode() === 200) {
            return $response()->toArray();
        }

        return [];
    }
}

所以，我们基本上正在向 https://reqres.in/api/users 的 URL 发送 GET 请求。

看，现在管理 API 是多么简单？

让我们看看另一个例子。

带有表单参数的 POST 请求

public function createUser(array $data)
{
    $response = $this->withFormParams($data)
            ->post('create');

    if ($response->getStatusCode() === 201) {
        return $response()->toArray();
    }

    return null;
}

默认头

有时我们需要将一些头与所有请求绑定。假设您想要处理 Github API，您必须在每个请求中发送带有头的 access_token。因此 APIZ 提供了一种方便的方式来处理这个问题。只需重写 AbstractApi::getDefaultHeaders()。

protected function getDefaultHeaders()
{
    return [
        'access_token' => $_ENV['GITHUB_ACCESS_TOKEN'],
    ];
}

酷，不是吗？

您可以使用所有 HTTP 动词，如 get、post 等，完全无忧。请参阅示例文件夹中的更多示例。

查询响应数据

有时我们从 API 接收巨大的有效负载作为响应。从如此大的有效负载中解析适当的数据相当令人畏惧。

不用担心！我们默认使用一个强大的查询解析器，名为 QArray，来解析和查询响应数据。

让我们看看如何使用此解析器来解析我们从之前的例子中的 getAllUsers 方法获得的响应。

public function getFirstUser()
{
    $users = $this->get('users');
    return $users->query()->from('data')->first();
}

我们在响应中的 data 键中获取用户列表。然后我们从其中收集第一个数据。看，多么简单！

您可以在这里找到 QArray 的详细用法。

此外，还有一款秘制配方等着您。

如果您不想像这样查询：$users->query()，您可以直接这样做：$users()。这意味着响应对象是可调用的，并且行为与调用 query() 方法完全一样。

欢迎您的到来。 :D

重写 HTTP 客户端

默认情况下，我们使用 Guzzle 作为我们的 HTTP 客户端。但您不必局限于使用此客户端。您可以使用自己的 PSR7 兼容的 HTTP 客户端与 Apiz 一起使用。只需将您的 HTTP 客户端实例传递给我们的 setClient() 方法即可。请参阅此处的示例。

以下是我们的 GuzzleClient，以了解您的客户端应该是什么样子

<?php

namespace Apiz\Http\Clients;

use Apiz\Http\AbstractClient;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;
use GuzzleHttp\Psr7\Uri;
use GuzzleHttp\Exception\GuzzleException;
use Psr\Http\Message\ResponseInterface;

// Your client must extend the `AbstractClient`
class GuzzleClient extends AbstractClient
{
    public function getRequestClass()
    {
        // Return the Request class name of your PSR7 supported Client
        // This Request class must implement the Psr\Http\Message\RequestInterface
        return Request::class;
    }

    public function getResponseClass()
    {
        // Return the Response class name of your PSR7 supported Client
        // This Response class must implement the Psr\Http\Message\ResponseInterface        
        return Response::class;
    }

    public function getUriClass()
    {
        // Return the Uri class name of your PSR7 supported Client
        // This Uri class must implement the Psr\Http\Message\UriInterface        
        return Uri::class;
    }

    /**
     * @param mixed ...$args
     * @return ResponseInterface
     * @throws GuzzleException
     */
    public function send(...$args)
    {
        // In this method, implement how your Client execute the Request sending
        $client = new Client();

        return $client->send(... $args);
    }
}

常见HTTP动词的方法列表

get(string $uri)
post(string $uri)
put(string $uri)
delete(string $uri)
head(string $uri)
options(string $uri)

可用方法列表

getPrefix():string：如果你需要，重写此方法来定义公共前缀
setClient($client)：传递一个PSR7支持的Client实例，仅在需要重写默认的Guzzle HTTP客户端时使用
withFormParams(array)：为POST、PATCH、UPDATE等请求传递表单参数数据
withHeaders(array)：传递头部数据
withQueryParams(array)：传递查询参数数据
withFormData(array)：传递多部分表单数据
getDefaultHeaders():array：如果有任何默认头部，重写以定义默认头部
getDefaultQueries():array：如果有任何默认查询，重写以定义默认查询
skipDefaultHeaders(bool)
skipDefaultQueries(bool)
allowRedirects(array)
basicAuth(string $username, string $password [, array $options])
body(string)：设置请求体
json(array)：设置作为请求体的JSON数据
file(string $name, string $file_path, string $filename [, array $headers])
params(array $params)

贡献

请随意发送反馈和问题。也欢迎对改进此包的贡献。

nahid / apiz

维护者

详细信息