README

SDK для работы с программой лояльности Loymax.

Ускорит внедрение функциональности Loymax в Ваш продукт.

Loymax PHP SDK

Установка

composer require 15web/loymax-sdk

Требования

Минимальная версия PHP 8.2

SDK использует HTTP-клиент в соответствии с PSR-18 и логгер в соответствии с PSR-3.

По умолчанию используется Guzzle в качестве HTTP-клиента

Выбор HTTP-клиента и логгера.

Использование

use Studio15\Loymax\Loymax;

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

$loymax = Loymax::create('https://your-project.loymax.tech');

$merchants = $loymax->publicApi()->merchants()->getByIds();

Стандартная аутентификация, требующая введения логина и пароля

Документация https://docs.loymax.net/xwiki/bin/view/Main/Integration/Ways_to_use_API/Authorization_Service/Token_authorization
Схема авторизации в Личном кабинете https://docs.loymax.net/xwiki/bin/view/Main/Integration/Ways_to_use_API/Authorization_Service/Token_authorization/Authorization_in_Personal_Account_Scheme/

При включенной конфигурации IsPasswordRequired

use Studio15\Loymax\Loymax;

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

$loymax = Loymax::create('https://your-project.loymax.tech');

$token = $loymax->authApi()->issueAccessToken(
    username: '79990001234', // Логин (e-mail, номер телефона или номер карты)
    password: 'password', // Пароль
    clientIp: '1.2.3.4', // IP адрес пользователя
);

Передавайте реальный IP адрес пользователя в методах аутентификации и регистрации во избежание блокировок по количеству запросов с одного IP адреса

Двухфакторная аутентификация

При включенной конфигурации TwoFactorAuthenticationEnabled

use Studio15\Loymax\Loymax;

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

$loymax = Loymax::create('https://your-project.loymax.tech');

$twoFactorToken = $loymax->authApi()->issueAccessToken(
    username: '79990001234', // Логин (e-mail, номер телефона или номер карты)
    clientIp: '1.2.3.4', // IP адрес пользователя
);

$token = $loymax->authApi()->confirmTwoFactorAuthentication(
    twoFactorAuthToken: $twoFactorToken->twoFactorAuthToken,
    code: '123456', // Одноразовый пароль, полученный в SMS
);

Публичное API

use Studio15\Loymax\Loymax;

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

$loymax = Loymax::create('https://your-project.loymax.tech');

$twoFactorToken = $loymax->authApi()->issueAccessToken(
    username: '79990001234', // телефон
);

$token = $loymax->authApi()->confirmTwoFactorAuthentication(
    twoFactorAuthToken: $twoFactorToken->twoFactorAuthToken,
    code: '123456', // Код, полученный в SMS
);

/**
 * Получение баланса пользователя программы лояльности
 */
$balance = $loymax->publicApi(token: $token->accessToken)->user()->balance();

/** 
 * Получение публичной информации о торговых точках
 */
$merchants = $loymax->publicApi()->merchants()->getByIds();

Логирование

Все запросы и ответы логируются.

В конструктор требуется передать клиент, который реализует Psr\Log\LoggerInterface

Пример использования Monolog

composer require monolog/monolog

use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;
use Studio15\Loymax\Loymax;

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

$baseUri = 'https://your-project.loymax.tech';

$logger = new Logger('name');
$logger->pushHandler(new StreamHandler('log/loymax-info.log', Level::Info));

$loymax = new Loymax(
    baseUri: $baseUri,
    logger: $logger,
);

$merchants = $loymax->publicApi()->merchants()->getByIds();

Использование своего HTTP-клиента

По умолчанию в SDK используется Guzzle в качестве HTTP-клиента

Пример использования Symfony HTTP client

composer require symfony/http-client psr/http-client nyholm/psr7

use Studio15\Loymax\Loymax;
use Symfony\Component\HttpClient\Psr18Client;

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

$baseUri = 'https://your-project.loymax.tech';

$httpClient = (new Psr18Client())->withOptions(['base_uri' => $baseUri]);

$loymax = new Loymax(
    httpClient: $httpClient,
);

$merchants = $loymax->publicApi()->merchants()->getByIds();

Интеграция с фреймворками

Symfony

https://symfony.com/doc/current/index.html

Для использования класса Loymax в качестве сервиса требуется добавить в config/services.yaml

services: # ...
    Studio15\Loymax\Loymax:
        arguments:
            $httpClient: null
            $baseUri: 'https://your-project.loymax.tech'

Применение Symfony HTTP client вместо Guzzle

Laravel

https://laravel.com/docs/master

Добавьте в конфигурацию адрес вашего проекта:

config/services.php

<?php

return [
    //
    
    'loymax' => [
        'baseurl' => env('LOYMAX_API_BASEURL', 'https://your-project.loymax.tech'),
    ],
];

Для добавления в контейнер зарегистрируйте класс в сервис провайдере:

app/Providers/AppServiceProvider.php

use Studio15\Loymax\Loymax;

public function register(): void
{
    //
    
    $this->app->bind(
        abstract: Loymax::class,
        concrete: static fn (): Loymax => Loymax::create(config('services.loymax.baseurl')),
    );
}

Теперь достаточно подключить класс Loymax в любом месте, например в контроллере:

use Studio15\Loymax\Loymax;

class MyController extends Controller
{
    public function merchants(Loymax $loymax)
    {
        $merchants = $loymax->publicApi()->merchants()->getByUids();
    }
}

Дополнительная информация

Поддерживаемая версия Public API:

v1.2

Разработка

Loymax SDK — это Open Source продукт под лицензией MIT.

Помощь проекту:

Создать issue по вашей проблеме
Отправить pull request

Тестирование кода

Запуск проверок кода, тестов:

git clone git@github.com:15web/loymax-sdk.git
cd loymax-sdk
composer update
composer test

Проверка покрытия кода тестами:

Установить https://github.com/krakjoe/pcov/blob/develop/INSTALL.md

Запуск:

composer coverage

Поддержка и обратная связь

Если вы нашли ошибку, пожалуйста, отправьте вопрос напрямую в Github. Loymax SDK Issues

Как всегда, если Вам нужна дополнительная помощь, свяжитесь с нами https://www.15web.ru/contacts

15web / loymax-sdk

Maintainers

Details