README

此包已废弃

并将很快被完全移除。新包可在 此处获得。

请尽快更新您的应用程序！

PHP-客户端用于与 B2B API 交互

该包是 B2B API 服务的客户端实现，大大简化了与 B2B API 的交互，为开发者提供了清晰的 API。

所有 API 方法都伴随相应的 @phpdoc。

安装

要安装此包，请在终端中执行以下命令

$ composer require avto-dev/b2b-api-php "^2.5"

需要已安装的 composer。若未安装，请访问 此链接 进行安装。

请注意，需要固定安装包的主版本。

组件

该包由以下组件组成

每个组件在一定程度上是独立的，必要时可以单独使用。

请求生命周期

创建客户端实例时，会初始化 http 客户端和容器方法，每个容器方法负责一组方法。例如，用户级别的方法通过 $client->user()->someMethodName() 调用，而面向开发者的命令（在一定程度上重复用户级别的命令）通过 $client->dev()->user()->someMethodName() 调用。因此，使用 PHPStorm 等 IDE 进行开发时，在每次方法后按 cmd + 空格 组合键，您将看到它实现的方法列表以及嵌套的容器及其方法。

调用任何API方法时，都会检查是否启用了测试模式（配置参数is_test），如果是，则不会执行实际请求，而是返回预先准备好的模板内容，从而即使没有账户也能进行B2B API服务的集成。

无论是请求之前还是之后，都会执行为http客户端注册的所有callback函数。关于它们的使用，请参阅源代码以获取更多信息。

如果测试模式未激活，则将请求发送到B2B API服务。如果请求以不正确的代码结束，或者在其过程中出现错误，将抛出异常。因此，为了避免您的应用程序崩溃，请将所有客户端调用包裹在try { ... } catch (\Exception $e) { ... }块中。

B2B API返回响应后，您将获得一个类型为B2BResponse的对象，它不仅包含以数组形式存储的“原始”响应内容，还包含对其中数据的基类访问方法。更重要的是，如果响应包含数据块（例如报告内容、状态信息等），它会尝试解析返回数据的类型，并允许您通过其->data()方法访问它们。调用此方法时，您将获得一个类型为DataCollection（数据集合）的对象，它实现了一些方便的方法来与之交互，例如获取它们的数量、提取第一个元素、使用callback函数遍历它们等。

根据B2B API响应中的数据类型，将创建相应类型的对象，并具有自己的访问方法。例如，如果返回报告内容，您将可以使用方便的方法来获取源状态、源名称、获取报告生成状态、提取数据的方法等。最重要的是，检查集合中对象的类型（它是否与预期相符），并根据它使用相应的访问方法。

配置

为了指定客户端应使用哪个版本的B2B API、哪个URI以及其他一些选项，需要将它们以特定结构的形式传递给客户端类的构造函数。下面的示例显示了配置结构的示例。

<?php

$configuration = [
    'api' => [
        'versions' => [
            'v1' => [
                'base_uri' => 'https://some.host/b2b/api/v1',
            ],
        ],
    ],

    'use_api_version' => 'v1',

    // Блок 'client' используется *только* для функционального тестирования
    'client' => [
        'domain'          => '%имя_вашего_домена%',
        'username'        => '%имя_вашего_пользователя%',
        'password'        => '%пароль_вашего_пользователя%',
        'report_type_uid' => '%uid_типа_отчета%',
    ],

    'is_test' => false,
];

使用

以下是一个起点示例。

<?php

use AvtoDev\B2BApi\Clients\v1\Client;

require __DIR__ . '/vendor/autoload.php';

$configuration = [/* настройки работы клиента */];
$client        = new Client($configuration);
$response      = $client->dev()->ping();

var_dump($response);

示例

以下是一些使用客户端的示例。基本操作包括检查与B2B API服务的连接、订购报告以及获取其内容。

<?php

use AvtoDev\B2BApi\Tokens\AuthToken;
use AvtoDev\B2BApi\Clients\v1\Client;
use AvtoDev\B2BApi\References\QueryTypes;
use AvtoDev\B2BApi\Responses\DataTypes\User\BalanceData;
use AvtoDev\B2BApi\Responses\DataTypes\User\UserInfoData;
use AvtoDev\B2BApi\Responses\DataTypes\Report\ReportData;
use AvtoDev\B2BApi\Responses\DataTypes\Report\ReportStatusData;

$configuration   = [/* настройки работы клиента */];
$client          = new Client($configuration);
$token           = AuthToken::generate('имя_пользователя', 'пароль', 'имя_домена');
$report_type_uid = 'uid_вашего_типа_отчета';

// Проверка соединения
$response = $client->dev()->ping();
$result   = $response->getValue('value'); // pong

// Получение информации о текущем пользователе
$user_info = $client->user()->info($token)
                    ->data()
                    ->first();
if ($user_info instanceof UserInfoData) {
    $result = $user_info->getDomainUid(); // Вернёт имя домена пользователя, строкой
}

// Проверка доступности квоты по UID-у типа отчета
$client->user()->balance($token, $report_type_uid)
               ->data()
               ->each(function (BalanceData $balance_info) {
                   if ($balance_info->isDailyBalance()) {
                       // Получаем значение суточной квоты
                       $quote_use = $balance_info->getQuoteUse();
                   }
               });

// Генерация нового отчета по ГРЗ 'A111AA177'
$report_status = $client->user()->report()->make($token, QueryTypes::QUERY_TYPE_GRZ, 'A111AA177', $report_type_uid)
                        ->data()
                        ->first();
if ($report_status instanceof ReportStatusData) {
    $report_uid = $report_status->getUid(); // Вернёт UID отчета
}

// Получение имеющегося отчета
$report = $client->user()->report()->get($token, $report_uid)
                 ->data()
                 ->first();
if ($report instanceof ReportData) {
    $sources      = $report->getSourcesNames(); // Массив имен источников
    $is_completed = $report->generationIsCompleted(); // true, если генерация отчета завершена
    $vin_number   = $report->getField('identifiers.vehicle.vin'); // Вернет VIN-номер ТС (при его наличии)
    $engine_kw    = $report->getField('tech_data.engine.power.kw'); // Вернет мощность двигателя в КвТ
    $content      = $report->getContent(); // Весь контент отчета, массивом
}

提取数据的方法远不止上述示例中提到的那么多。如果您使用的是现代IDE进行开发，它们都会为您提供带有详细描述的提示。

测试

该包使用phpunit框架进行测试。要在终端中运行测试，请执行以下操作：

$ composer test

功能测试

还有执行一些功能测试（执行对B2B API服务的实际请求）的能力。为此，请在终端中执行以下操作：

$ git clone git@github.com:avto-dev/b2b-api-php.git ./b2b-api-php && cd $_
$ composer install
$ composer test

创建一个名为./tests/env.php的文件，并指定客户端将使用的参数（有关详细信息，请参阅“配置”部分），将is_test的值设置为false。然后，在终端中执行以下操作：

$ php ./vendor/bin/phpunit --group=feature

变更日志

变更日志可以在此处找到。

支持

如果您发现任何包错误，请在当前仓库中 创建一个问题。

许可证

这是一个开源软件，采用MIT许可证授权。