README

用于与 Yclients 服务 API v1.0 交互的 SDK

该库是 YclientsOpenApi 包的包装器，允许使用 Yclients API 和 PHP 8.1+。

处于开发中，版本可能不具备向下兼容性。变化日志可以在 Changelog 中找到。

安装

composer vgrish/yclients-sdk-php

快速入门

use Vgrish\Yclients\Yclients;

$yc = Yclients::getInstance()
    ->setPartnerToken('Partner_token')
    ->setUserToken('User_token');

//Конструктор запросов
$auth = $yc->query()
    ->user()
    ->auth()
    ->param([
        'login'    => 'телефон пользователя',
        'password' => 'пароль пользователя',
    ])
    ->create();

//Получаем токен пользователя
$userToken = $auth->object()->getUserToken();

//Устанавливаем токен пользователя
$yc->setUserToken($userToken);

//Получаем клиентов компании
$clients = $yc->query()
    ->clients()
    ->path('company_id', '111111')
    ->param([
        'fields' => [
            'id',
            'name',
            'phone',
            'email',
        ],
    ])
    ->pageSize(5)
    ->page(1)
    ->get();

foreach ($clients->objects() as $client) {
    var_dump($client->getId().':'$client->getName());
}

特性

该库提供查询构建器（Query）以与 API 交互。

查询构建器

允许通过 fluent-链式方法收集 Yclients API 的查询。查询构建器通过库的基本对象的 query() 方法调用。

use Vgrish\Yclients\Yclients;

$yc = Yclients::getInstance()
    ->setPartnerToken('Partner_token')
    ->setUserToken('User_token');
$yc->query()->...;

查询构建方法

段

分为两种类型

endpoint - 查询后的第一个段。例如：clients()、loyalty()。
segment - 在 endpoint 后的段。例如：auth()、card()。

段可以有各种嵌套段和方法，这些方法属于段表示的实体。

查询路径

path() 方法用于形成查询路径参数。可以多次调用该方法或使用数组应用多个参数。

$yc->query()
    ->client()
    ->path('company_id', '11111')
    ->path('id', '22222222')
    //или
    ->path(['company_id' => '11111', 'id' => '22222222'])
    //или
    ->path([
       ['company_id', '11111'],
       ['id', '22222222'],
    ])
    ->get();

查询参数

param() 方法用于形成查询参数。可以多次调用该方法或使用数组应用多个参数。

$yc->query()
    ->loyalty()
    ->transactions()
    ->path('chain_id', '33333')
    ->param([
         'created_after'  => '2024-07-10',
         'created_before' => '2024-07-31',
         'company_ids'  => '204265',
         ['types', [5, 6]],
    ])
    ->get([]);

page($value) - 设置分页页码。
count($value) - 设置选择结果的数量。
pageSize($value) - 设置选择结果的数量。（不同实体有不同的查询参数）

发送查询的方法

查询（$request）可以直接以数组格式传递给查询方法。

create($request) - 用于创建实体的 POST 查询。

$yc->query()
    ->user()
    ->auth()
    ->create([
        'login'    => 'login',
        'password' => 'password',
    ]);

get($request) - 用于获取实体的 GET 查询。

$yc->query()
    ->client()
    ->get()

update($request) - 用于更新实体的 PUT 查询。

$yc->query()
    ->client()
    ->get()
    ->update(['name' => 'новое имя клиента'])

remove($request) - 用于删除实体的 DELETE 查询。

$yc->query()
    ->client()
    ->get()
    ->remove()

迭代结果

可以使用 objects() 方法获取集合对象。因此，可以通过以下方式组织结果的遍历：

$clients = $yc->query()
    ->clients()
    ->path('company_id', '111111')
    ->param([
        'fields' => [
            'id',
            'name',
            'phone',
            'email',
        ],
    ])
    ->pageSize(200)
    ->page(1)
    ->get();
foreach ($clients->objects() as $client) {
    var_dump($client);
}

然而，如果需要遍历整个集合，其大小超过限制，则需要多次请求集合，并更改参数 page。为了避免手动组织此类遍历，可以使用 generator() 方法。它返回一个生成器，遍历当前 page 到最后一个元素（如果需要，将发送新的请求）。

$generator = $yc->query()
    ->clients()
    ->path('company_id', '111111')
    ->pageSize(200)
    ->generator(function ($builder) {
         $params = $builder->params();
         //Можно прекратить перебор коллекции
         if ($params['page'] > 20) {
             return;
         }
         return $builder->get();
    });
foreach ($generator as $client) {
    $clients[] = $client;
}

vgrish / yclients-sdk-php

维护者

详细信息