README

MikBiLL PHP SDK для работы с клиентами. Получение токена, данных клиентов. Управление подписками, отписками и т.д...

⚙️ Требования

Рекомендуемая версия PHP >=8.0 и composer.

📦 Установка

composer require haikiri/mikbill

📚 Ссылки

📂 Структура

Так как официальная документация и сам MikBiLL API не использует систему версирования, данная библиотека будет всегда актуальной и по мере возможностей сохранять старые методы взаимодействия.

Эта SDK библиотека будет наполняться по мере необходимости, возможностей и откликов. Теперь большинство методов и примеры их использования будут перечислены либо в папке тестирования tests либо в wiki. Ниже в структуре будут перечислены ссылки на вики, классы или тесты...

На что вы можете рассчитывать:

[F] - Функционал завершён.
[MD] - Основной функционал завершён. (Дочерние методы, возможно, могут быть добавлены позднее)
[P] - В приоритете. (По планам завершить в ближайшее время)
[MP] - Средний приоритет. (Было бы хорошо иметь, но не критично, когда-нибудь...)
[LP] - Низкий приоритет. (Возможно появление базового функционала для некоторых методов в будущем)
[NP] - Не запланирован. (Может быть в будущем/По запросу)
[??] - Требуется проверка.

Все запросы в Billing Api должны быть подписаны общим HMAC ключом. Пример смотри ниже.

Все запросы в Cabinet Api должны быть подписаны Bearer токеном клиента. Пример получения токена для бота либо для личного кабинета.

Billing API
- Users [F]
  - Получить токен клиента [F]
  - Поиск клиента [F]
  - Kick User [deprecated]
  - Bind User [deprecated]
Cabinet API
- Auth [F]
  - Авторизация по логину и паролю
  - Авторизация по телефону
    - OTP-Код
- Tickets [F]
- Common [F]
  - Время сервера [F]
  - IP Клиента [F]
  - Версия MikBiLL [F]
  - Конфигурация [MD]
  - Контакты компании [F]
  - Меню сайта [F]
- Packet [MD]
  - Доступные тарифы [F]
  - Информация об тарифе [MD]
- User [MD]
  - Contacts [P]
  - Данные Клиента [F]
  - Напомнить пароль [F]
  - Изменить пароль [F]
  - Изменить тариф [F]
- Register Hotpost [NP]
- Payments [MD]
  - Voucher [F]
  - Прочие методы... [NP]
- Services [MP]
  - Услуга Турбо [F]
  - Услуга Заморозка [F]
  - Real IP [MP]
  - Услуга Кредит [F]
  - Change MAC [LP]
  - Money Transfers [LP]
- Subscriptions [MD]
  - Additional [F]
  - Middleware [F]
  - Other [F]
  - Прочие методы... [NP]
- Devices [NP]
- Reports [F]
  - Платежи [F]
  - Сессии [F]
- News [F]
  - Новости [F]

🧯 Обработка ошибок

Проект поддерживает легкую обработку ошибок с помощью исключений. Если вам необходимо более детальная возможность отлова ошибок, вы можете заменить входную точку этого SDK на свой класс. Вы не в клетке. Пример с чего начать собственную реализацию входной точки SDK смотри по ссылке: Своя реализация sendRequest. Строка 100.

Исключения, которые могут быть выброшены в стандартной реализации SDK:
- BillApiException — отлавливает ответы биллинга и возвращает оригинальный код и текст ошибки.
- UnauthorizedException — вызывается если произошла ошибка получения данных в следствии ошибки авторизации.
- Throwable — используйте с осторожностью для глубокого отлова всех остальных ошибок.

Important

Полный список исключений можете найти в src/Exception

Оборачивай вызовы в try-catch чтобы отловить исключения:

try {
    /**
    * Здесь выполняйте запросы к API, чтобы отлавливать ошибки.
    */

} catch (\Haikiri\MikBiLL\Exception\UnauthorizedException $e) {
    // Сами придумаете как обрабатывать такие ошибки...
	echo "<hr><h2>Не удалось авторизовать запрос: <code>[{$e->getCode()}]</code></h2>";
	echo $e->getMessage();
} catch (\Haikiri\MikBiLL\Exception\BillApiException $e) {
	echo "<hr><h2>MikBiLL прислал в ответ ошибку: <code>[{$e->getCode()}]</code></h2>";
	echo $e->getMessage();
} catch (\Exception $e) {
	echo "<hr><h2>Неизвестная ошибка: <code>[{$e->getCode()}]</code></h2>";
	echo $e->getMessage();
}

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

Инициализация проекта

Используй эту базовую конструкцию где-нибудь в своём проекте, чтобы инициализировать SDK:

require "vendor/autoload.php";

use Haikiri\MikBiLL\MikBiLLApi;

$MikBiLL = new MikBiLLApi(
    url: "https://api.example.com/", # Твой Api сервер.
    key: "yourApiSignKey", # Твой Api ключ для подписи административных billing запросов.
//    debug: false, # Укажи `true` – чтобы включить отладку запросов.
);

Проксирование

Если по какой-либо причине есть необходимость в прокси-сервере:

$MikBiLL->isProxy = false; # true чтобы включить
$MikBiLL->proxy_addr = "10.11.12.13";
$MikBiLL->proxy_port = 8080;
$MikBiLL->proxy_user = "userName";
$MikBiLL->proxy_pass = "userPassword";

Note

По умолчанию используется socks5. Ты можешь добавить следующий параметр для использования других версий, например 4:

$MikBiLL->proxy_type = CURLPROXY_SOCKS4;

💬 Напоследок:

Не забывай после получения токена клиента ЗАПИСАТЬ ЕГО!

Токен нужно записывать в stateless хранилище каждый раз для отправки запросов к Cabinet API. Пример записи токена:

$token = "Здесь Bearer токен клиента.";
$MikBiLL->setUserToken($token);

Обрати внимание, что почти над каждым методом в исходном коде были оставлены комментарии. Но некоторые поля описаны неполно, либо вообще не описаны, потому что официальной документации на каждое поле БД – нет. Будет круто, если ты поможешь заполнить пробелы и знаешь что за что отвечает...

Если в каком-то объекте нет нужной модели, нет времени ждать внесения изменений, ты можешь использовать метод:

getAsArray – он вернёт тебе традиционный response["data"] массив данных, напрямую из запроса.

getData - он позволит обращаться к вложенным массивам в стиле "точки.доступа", например getData("data.info.user").

Если хочешь дополнить библиотеку — напиши по контактам в composer.json.

haikiri / mikbill

Maintainers

Details