README

本包允许您轻松与Plytix API交互。

安装

您可以通过composer安装此包

composer require esign/laravel-plytix

包将自动注册服务提供者。

接下来，您可以发布配置文件

php artisan vendor:publish --provider="Esign\Plytix\PlytixServiceProvider" --tag="config"

配置文件将以config/plytix.php的形式发布，内容如下

<?php

use Esign\Plytix\Enums\RateLimitingPlan;

return [
    /**
     * The API key to be used for authenticating with the Plytix API.
     */
    'api_key' => env('PLYTIX_API_KEY'),

    /**
     * The API password to be used for authenticating with the Plytix API.
     */
    'api_password' => env('PLYTIX_API_PASSWORD'),

    'authenticator_cache' => [
        /**
         * The key that will be used to cache the Plytix access token.
         */
        'key' => 'esign.plytix.authenticator',

        /**
         * The cache store to be used for the Plytix access token.
         * Use null to utilize the default cache store from the cache.php config file.
         * To disable caching, you can use the 'array' store.
         */
        'store' => null,
    ],

    'rate_limiting' => [
        /**
         * The rate limits to be used for the Plytix API.
         */
        'plan' => RateLimitingPlan::FREE,

        /**
         * The cache store to be used for the Plytix rate limits.
         * Use null to utilize the default cache store from the cache.php config file.
         * To disable caching, you can use the 'array' store.
         */
        'cache_store' => null,
    ],
];

用法

本包利用Saloon向Plytix API发送请求，提供了一种优雅的API交互方式。

身份验证

在配置文件中配置您的API密钥和密码后，身份验证令牌将由包自动管理。无需手动处理身份验证令牌。

速率限制

Plytix API根据您的订阅计划执行速率限制。您可以在config/plytix.php文件中的rate_limiting部分配置这些速率限制。

发送请求

要向Plytix API发送请求，您可以使用Esign\Plytix\Plytix连接器。
您可以在src/Requests目录中探索所有可用的请求类。
以下是发送请求的示例

use Esign\Plytix\Plytix;
use Esign\Plytix\Requests\ProductRequest;

class MyCommand
{
    public function handle(): int
    {
        $plytix = Plytix::make();
        $response = $plytix->send(new ProductRequest('583bef16-2197-46dd-90ce-9f4210bef5ef'));

        return self::SUCCESS;
    }
}

响应处理

本包使用DTO（数据传输对象）简化API响应的工作。您可以从响应中检索DTO，如下所示

$plytix = Plytix::make();
$response = $plytix->send(new ProductRequest('583bef16-2197-46dd-90ce-9f4210bef5ef'));
$product = $response->dtoOrFail();

或者，您也可以检索原始响应数据

$plytix = Plytix::make();
$response = $plytix->send(new ProductRequest('583bef16-2197-46dd-90ce-9f4210bef5ef'));
$data = $response->body();

分页请求

对于返回分页数据的端点，您可以轻松地遍历响应

$plytix = Plytix::make();
$paginator = $plytix->paginate(new ProductSearchRequest());

foreach ($paginator as $response) {
    $products = $response->dtoOrFail();
}

此外，您还可以使用items或collect方法遍历这些页面。
有关更多信息，请参阅Saloon分页文档。

$plytix = Plytix::make();
$paginator = $plytix->paginate(new ProductSearchRequest());

foreach ($paginator->items() as $product) {
    // Do something with the product
}

$paginator->collect()->each(function ($product) {
    // Do something with the product
});

创建请求

扩展现有请求

如果您需要自定义或扩展现有请求，可以通过扩展基础请求类创建自己的请求类

use Esign\Plytix\Requests\ProductRequest;

class MyCustomProductRequest extends ProductRequest
{
    protected function defaultQuery(): array
    {
        return [
            'customer-query-param' => 'value',
        ];
    }

}

创建自定义请求

如果您需要的请求由包提供，您可以使用Saloon创建自定义请求。首先安装Saloon Laravel插件，然后使用以下命令

php artisan saloon:request Plytix MyCustomRequest

use Saloon\Enums\Method;
use Saloon\Http\Request;

class MyCustomRequest extends Request
{
    protected Method $method = Method::GET;

    public function resolveEndpoint(): string
    {
        return '/example';
    }
}

测试

composer test

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。