README

本软件包是 Atera API 的轻量级 PHP 客户端 / SDK。

安装
身份验证
使用方法
- 请求
- 资源
- 响应
- 实体
- 分页
- 扩展 SDK

安装

此库需要 PHP >=8.1。

您可以通过 composer 安装此软件包

composer require bluerocktel/atera-api-php-client

身份验证

Atera API 的身份验证使用从 Atera 管理面板中检索的 API 令牌完成。有关更多信息，请参阅 Atera 文档。

use BlueRockTEL\AteraClient\AteraConnector;

$api = new AteraConnector(
    apiToken: 'secret_token',
    apiUrl: 'https://app.atera.com/api', // optional
);

实例化 AteraConnector 类后，您就可以开始查询 API。

$response = $api->agent()->index();

var_dump(
  $response->failed(), // true is the request returned 4xx or 5xx code.
  $response->json(),   // json response as an array
);

使用方法

要查询 API，您可以直接调用每个 API 端点请求，或者使用提供的资源类，这些类将请求分组到簇中。

使用请求

使用单个请求非常简单。您可以使用 AteraConnector 类的 call() 方法向实例发送所需请求。

use BlueRockTEL\AteraClient\AteraConnector;
use BlueRockTEL\AteraClient\Endpoints;

$api = new AteraConnector('secret_token');

$response = $api->call(
  new Endpoints\Contacts\GetContactRequest(id: $contactId)
);

使用资源

使用资源是查询 API 的更方便的方法。每个资源类根据特定的 API 命名空间（客户、代理、联系人...）对请求进行分组。

use BlueRockTEL\AteraClient\AteraConnector;

$api = new AteraConnector('secret_token');

$query = [
    'searchOptions.email' => 'test@example.com',
];

$response = $api->contact()->index(
    query: $query,
    perPage: 20,
    page: 1,
);

资源类通常提供（但不限于）以下方法：

class NamespaceResource
{
    public function index(array $params = [], int $perPage = 20, int $page = 1): Response;
    public function show(int $id): Response;
    public function store(Entity $entity): Response;
    public function update(Entity $entity): Response;
    public function upsert(Entity $entity): Response;
    public function delete(int $id): Response;
}

👉 upsert() 方法是一个简单的别名：如果给定的实体有一个 ID，它将调用 update() 方法，否则调用 store() 方法。

您可以使用 AteraConnector 实例访问这些命名空间资源。

$connector = new AteraConnector(...);

$connector->agent(): Resources\AgentResource
$connector->customer(): Resources\CustomerResource
$connector->contact(): Resources\ContactResource
...

如果需要，也可以手动创建所需的资源实例。

use BlueRockTEL\AteraClient\AteraConnector;
use BlueRockTEL\AteraClient\Resources\AgentResource;

$api = new AteraConnector();
$resource = new AgentResource($api);

$agent = $resource->show($agentId);
$resource->upsert($agent);

响应

无论您使用请求还是资源，响应始终是 Saloon\Http\Response 类的实例。它提供了一些有用的方法来检查响应状态和获取响应数据。

// Check response status
$response->ok();
$response->failed();
$response->status();
$response->headers();

// Get response data
$response->json(); # as an array
$response->body(); # as an raw string
$response->dtoOrFail(); # as a Data Transfer Object

您可以通过阅读此 SDK 使用的 Saloon 文档来了解有关响应的更多信息。

实体（DTO）

在处理 API 时，处理原始或 JSON 响应可能会很繁琐且不可预测。

为了使操作更简单，此 SDK 提供了一种将响应数据转换为数据传输对象（DTO）（以后称为实体）的方法。这样，您就可以了解您正在处理的数据的结构，并且可以使用对象类型属性而不是无类型的数组键来访问数据。

$response = $api->agent()->show(id: 92);

/** @var \BlueRockTEL\AteraClient\Entities\Agent */
$agent = $response->dtoOrFail();

虽然您可以使用 dto() 方法将响应数据转换为实体，但建议您使用 dtoOrFail() 方法。如果响应状态不是 2xx，此方法将抛出异常，而不是返回一个空的 DTO。

您仍然可以使用 DTO 的 getResponse() 方法访问底层响应对象。

$entity = $response->dtoOrFail();   // \BlueRockTEL\AteraClient\Contracts\Entity
$entity->getResponse();             // \Saloon\Http\Response

有关在 Saloon 文档中与数据传输对象一起工作的更多信息，请参阅。

创建/更新/更新路由通常会请求 DTO 作为第一个参数

use BlueRockTEL\AteraClient\Entities\Customer;

// create
$response = $api->customer()->store(
    customer: new Customer(
        CustomerName: 'Acme Enterprise',
        City: 'Paris',
    ),
);

$customer = $response->dtoOrFail();

// update
$customer->CustomerName = 'Acme Enterprise Inc.';
$api->customer()->update($customer);

分页

在某些索引/搜索路由上，Atera API 将使用分页。如果您需要迭代端点的所有页面，使用连接器的 paginate() 方法可能会很方便。

# Create a PagedPaginator instance
$paginator = $api->paginate(new GetCustomersRequest());

# Iterate on all pages entities, using lazy loading for performance
foreach ($paginator->items() as $customer) {
    $name = $customer->CustomerName;
    $city = $customer->City;
}

有关懒加载分页的更多信息，请参阅 Saloon 文档。

扩展 SDK

您可以通过创建自己的资源、请求和实体来轻松扩展 SDK。

然后，通过扩展 AteraConnector 类，将您的新资源添加到连接器中。

use BlueRockTEL\AteraClient\AteraConnector;

class MyCustomConnector extends AteraConnector
{
    public function defaultConfig(): array
    {
        return [
            'timeout' => 120,
        ];
    }

    public function customResource(): \App\Resources\CustomResource
    {
        return new \App\Resources\CustomResource($this);
    }
}

$api = new MyCustomConnector('secret_token');
$api->customResource()->index();

bluerocktel / atera-api-php-client

维护者

详细信息