README

This package allow you to easily interact with the Plytix API.

Important

It is recommended not to migrate to v2 of this package yet. While it was initially based on v2 of Plytix's API, their API was later reclassified as beta after some changes were reverted. This package now reflects those reversions and is tagged as an alpha release, as further breaking changes may occur.

Installation

You can install the package via composer:

composer require esign/laravel-plytix

The package will automatically register a service provider.

Next up, you can publish the configuration file:

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

The config file will be published as config/plytix.php with the following content:

<?php

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 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,
    ],
];

Usage

This package leverages Saloon for sending requests to the Plytix API, providing an elegant way to interact with the API.

Authentication

After configuring your API key and password in the config file, authentication tokens are automatically managed by the package. There's no need to manually handle authentication tokens.

Rate limiting

The Plytix API enforces rate limits based on the subscription plan you’re on. You can configure these rate limits in the boot method of your AppServiceProvider:

use Esign\Plytix\Facades\RateLimiter;
use Saloon\RateLimitPlugin\Limit;

public function boot(): void
{
    RateLimiter::setLimits(
        Limit::allow(20)->everySeconds(10),
        Limit::allow(5000)->everyHour(),
    );
}

Sending requests

To send requests to the Plytix API, you may use the Esign\Plytix\Plytix connector.
You can explore all the available request classes in the src/Requests directory.
Each version of the Plytix API, such as V1 or V2, has its own folder. Note that some requests are only accessible in certain versions.
Here’s an example of sending a request:

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

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

        return self::SUCCESS;
    }
}

Response handling

This package uses DTOs (Data Transfer Objects) to simplify working with API responses. You can retrieve the DTO from the response like this:

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

Alternatively, you can retrieve the raw response data:

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

Paginating requests

For endpoints that return paginated data, you can easily paginate through the responses:

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

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

Additionally, you may also traverse through these pages using the items or collect methods.
For more information, refer to the Saloon pagination documentation.

$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
});

Creating requests

Extending existing requests

If you need to customize or extend an existing request, you can create your own request class by extending the base request class:

use Esign\Plytix\Requests\ProductRequest;

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

}

Creating custom requests

If the request you need is not provided by the package, you can create a custom request using Saloon. First, install the Saloon Laravel plugin, then use the following command:

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';
    }
}

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.

esign / laravel-plytix

Maintainers

Details