README

本包是BlueRockTEL管理API的轻量级PHP包装器/SDK。

安装
身份验证
- 客户端代码授权
- 密码授权
使用方法
- 请求
- 资源
- 响应
- 实体
- 分页
- 扩展SDK

安装

此库需要PHP >=8.1。

您可以通过composer安装此包

composer require bluerocktel/php-sdk

身份验证

BlueRockTEL API支持OAuth2进行身份验证。然而，此包目前仅支持密码授权身份验证流程。

客户端代码授权

尚未支持。

密码授权

要使用您的常规BlueRockTEL凭据连接，首先初始化BlueRockTELConnector类，提供您的实例URL、电子邮件和密码

use BlueRockTEL\SDK\BlueRockTELConnector;

$api = new BlueRockTELConnector(
  'https://telecomxxxx-admin.bluerocktel.net/api/',
  'developers@bluerocktel.com',
  'secret',
);

如果连接器无法从提供的凭据中检索Bearer令牌，将抛出BlueRockTEL\SDK\Exceptions\AuthenticationException异常。

否则，您可以通过调用辅助资源的version()方法开始测试API

$response = $api->helper()->version();

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

使用方法

查询API，您可以选择单独调用每个API端点请求，或者使用提供的资源类，这些类将请求分组到集群中。

使用请求

使用单个请求很简单。您可以使用BlueRockTELConnector类的call()方法将所需的请求发送到实例

use BlueRockTEL\SDK\BlueRockTELConnector;
use BlueRockTEL\SDK\Endpoints;

$api = new BlueRockTELConnector(BLUEROCKTEL_API_URL, BLUEROCKTEL_API_USERNAME, BLUEROCKTEL_API_PASSWORD);

$response = $api->call(
  new Endpoints\GetVersionRequest()
);

$response = $api->call(
  new Endpoints\Prospects\GetProspectRequest(id: $prospectId)
);

使用资源

使用资源是查询API的更便捷方式。每个资源类根据特定的API命名空间（客户、潜在客户...）对请求进行分组。

use BlueRockTEL\SDK\BlueRockTELConnector;

$api = new BlueRockTELConnector(BLUEROCKTEL_API_URL, BLUEROCKTEL_API_USERNAME, BLUEROCKTEL_API_PASSWORD);

$query = [
    'filter' => [
        'name' => 'Acme Enterprise',
        'term_match' => 'PR0001'
    ],
    'sort' => '-created_at',
];

$response = $api->prospect()->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()方法。

可以使用BlueRockTELConnector实例访问每个命名空间资源

$connector = new BlueRockTELConnector(...);

$connector->note(): Resources\NoteResource
$connector->prospect(): Resources\ProspectResource
$connector->customerFile(): Resources\CustomerFileResource
...

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

use BlueRockTEL\SDK\BlueRockTELConnector;
use BlueRockTEL\SDK\Resources\ProspectResource;

$api = new BlueRockTELConnector();
$resource = new ProspectResource($api);

$prospect = $resource->show($prospectId);
$resource->upsert($prospect);

响应

无论您是使用请求还是资源，响应始终是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->prospect()->show(id: 92);

/** @var \BlueRockTEL\SDK\Entities\Prospect */
$prospect = $response->dtoOrFail();

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

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

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

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

创建/更新/upsert路由通常要求将DTO作为第一个参数

use BlueRockTEL\SDK\Entities\Prospect;

// create
$response = $api->prospect()->store(
    prospect: new Prospect(
        name: 'Acme Enterprise',
        customerAccount: 'PR0001',
    ),
);

$prospect = $response->dtoOrFail();

// update
$prospect->name = 'Acme Enterprise Inc.';
$api->prospect()->update($prospect);

分页

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

$query = [
  'sort' => 'created_at',
];

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

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

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

扩展SDK

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

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

use BlueRockTEL\SDK\BlueRockTELConnector;

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

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

$api = new MyCustomConnector(BLUEROCKTEL_API_URL, BLUEROCKTEL_API_USERNAME, BLUEROCKTEL_API_PASSWORD);
$api->customResource()->index();

bluerocktel / php-sdk

维护者

详细信息