Баланс пользователя

API Документация: Billing\Api\Balance

Описание

Класс Balance — это API для управления балансом пользователей в системе DLE Billing. Он предоставляет методы для:

Начисления и списания средств
Создания счетов (инвойсов)
Проверки баланса
Записи истории операций
Управления транзакциями
Отправки уведомлений

Класс реализует паттерн Singleton — существует только один экземпляр в рамках запроса.

Inicialization

`Init(?array $params = []) : self`

Инициализирует и возвращает экземпляр класса Balance.

Параметр	Тип	Описание
`$params`	`array\|null`	Параметры конфигурации (опционально). Если не указан, загружается из `ENGINE_DIR/data/billing/config.php`

Возвращает: Экземпляр класса Balance

Исключения:

\BalanceException — если не удалось найти файл конфигурации

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

$balance = \Billing\Api\Balance::Init();
// или с параметрами
$balance = \Billing\Api\Balance::Init(['fname' => 'balance', 'currency' => 'руб,руб,руб']);

Методы управления балансом

`From(int $userId = 0, string $userLogin = '', float $sum = 0) : self`

Списать средства с баланса пользователя.

Параметр	Тип	Описание
`$userId`	`int`	ID пользователя (опционально)
`$userLogin`	`string`	Логин пользователя (опционально, если не указан `$userId`)
`$sum`	`float`	Количество средств для списания

Возвращает: $this (для цепочения методов)

Исключения: \BalanceException — если пользователь не найден

Пример:

$balance->From(userId: 123, sum: 50.00);

`To(int $userId = 0, string $userLogin = '', float $sum = 0) : self`

Начислить средства на баланс пользователя.

Параметр	Тип	Описание
`$userId`	`int`	ID пользователя (опционально)
`$userLogin`	`string`	Логин пользователя (опционально)
`$sum`	`float`	Количество средств для начисления

Возвращает: $this

Исключения: \BalanceException

Пример:

$balance->To(userLogin: 'john_doe', sum: 100.00);

`Check(int $userId = 0, string $userLogin = '', float $sum = 0) : self`

Проверить, достаточно ли средств у пользователя для оплаты.

Параметр	Тип	Описание
`$userId`	`int`	ID пользователя
`$userLogin`	`string`	Логин пользователя
`$sum`	`float`	Необходимая сумма

Возвращает: $this

Исключения:

\BalanceException с ключом 'balance.check' — если средств недостаточно

Пример:

try {
    $balance->Check(userId: 123, sum: 75.00);
    // средств достаточно, продолжаем
} catch (\BalanceException $e) {
    // недостаточно средств
}

Методы для счетов (инвойсов)

`createInvoice(...) : int`

Создать счет на оплату.

Параметр	Тип	Описание
`$userId`	`int`	ID пользователя (опционально)
`$userLogin`	`string`	Логин пользователя (опционально)
`$userAnonymous`	`string`	Имя анонимного пользователя или IP (опционально)
`$payment`	`string`	ID платежной системы
`$sum_get`	`float`	Сумма начисления
`$sum_pay`	`float`	Сумма оплаты
`$payer_info`	`mixed`	Информация о плательщике (строка или массив)
`$handler`	`string`	Обработчик платежа

Возвращает: int — ID созданного счета (invoice_id)

Исключения: \BalanceException

Пример:

$invoiceId = $balance->createInvoice(
    userId: 123,
    payment: 'webmoney',
    sum_get: 0,
    sum_pay: 150.00,
    payer_info: ['name' => 'Иван', 'email' => 'ivan@example.com'],
    handler: 'webmoney_handler'
);

`checkDouble(bool $check = true) : self`

Настроить проверку на дубликаты счетов.

Параметр	Тип	Описание
`$check`	`bool`	`true` — проверять дубликаты, `false` — не проверять

Возвращает: $this

Примечание: При обнаружении дубликата метод createInvoice возвращает ID существующего счета вместо создания нового.

Пример:

$balance->checkDouble(true);
$invoiceId = $balance->createInvoice(/* ... */);

Методы транзакций

`Transaction() : self`

Начать транзакцию базы данных.

Возвращает: $this

Пример:

$balance->Transaction();
try {
    $balance->From(userId: 123, sum: 50.00);
    $balance->To(userId: 456, sum: 50.00);
    $balance->Commit();
} catch (\Exception $e) {
    $balance->Rollback();
}

`Commit() : void`

Завершить транзакцию (commit).

`Rollback() : void`

Отменить транзакцию (rollback).

Методы истории и уведомлений

`Comment(...) : self`

Записать операцию в журнал и отправить уведомления.

Параметр	Тип	Описание
`$userId`	`int`	ID пользователя
`$userLogin`	`string`	Логин пользователя
`$plus`	`float`	Начисленная сумма (0 если нет)
`$minus`	`float`	Списанная сумма (0 если нет)
`$comment`	`string`	Комментарий к операции
`$plugin_id`	`int`	ID плагина (опционально)
`$plugin_name`	`string`	Название плагина (опционально, по умолчанию `'api'`)
`$pm`	`bool`	Отправить внутреннее сообщение (опционально)
`$email`	`bool`	Отправить email (опционально)

Возвращает: $this

Исключения: \BalanceException, \Exception

Пример:

$balance->Comment(
    userId: 123,
    plus: 100.00,
    comment: 'Бонус за регистрацию',
    plugin_name: 'registration',
    plugin_id: 5,
    email: true
);

`sendCommission(float $sum, string $comment, string $plugin = '', int $plugin_id = 0) : self`

Отправить комиссию системному пользователю (администратору).

Параметр	Тип	Описание
`$sum`	`float`	Сумма комиссии
`$comment`	`string`	Комментарий
`$plugin`	`string`	Название плагина (опционально)
`$plugin_id`	`int`	ID плагина (опционально)

Возвращает: $this

Исключения: \BalanceException

Примечание: Требуется настройка commission и admin в конфигурации.

`sendEvent(...$hook_new_data) : self`

Отправить событие в плагины (хук-система).

Параметр	Тип	Описание
`$hook_new_data`	`mixed`	Дополнительные данные события (опционально)

Возвращает: \Billing\Api\Balance

Примечание:

Максимальная длина цепочки событий: 10 (MAX_HOOK_EVENTS)
Плагины получают данные через метод pay() класса \Billing\Hooks

Методы форматирования

`Convert(mixed $value = 0, ?bool $separator_space = false, ?string $format = '', ?bool $declension = false) : float|string`

Конвертировать и форматировать число в строку с валютой.

Параметр	Тип	Описание
`$value`	`mixed`	Число для форматирования
`$separator_space`	`bool\|null`	`true` — использовать пробел как разделитель (например, `1 000`)
`$format`	`string\|null`	`'int'` — без десятичных знаков, иначе 2 знака
`$declension`	`bool\|null`	`true` — добавить падеж валюты (например, `руб.`)

Возвращает: float|string — форматированное число

Пример:

$balance->Convert(1234.56, separator_space: true, declension: true);
// "1 234.56 руб."

`Declension(mixed $value, ?array $titles = []) : string`

Получить падеж валюты для числа.

Параметр	Тип	Описание
`$value`	`mixed`	Число
`$titles`	`array\|null`	Массив 3 названий для падежей (опционально, по умолчанию из конфига)

Возвращает: string — падеж валюты

Пример:

$balance->Declension(1);  // "руб."
$balance->Declension(2);  // "руб."
$balance->Declension(5);  // "руб."

// С собственными названиями
$balance->Declension(1, ['доллар', 'доллара', 'долларов']);
// "доллар"

Исключения

Класс исключений: \BalanceException

Ключи ошибок:

'balance.check' — недостаточно средств
'user.not_found:X' — пользователь не найден
'Unable to load config file' — файл конфигурации не найден

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

Начисление и списание с уведомлением

$balance = \Billing\Api\Balance::Init();

// Начислить бонус
$balance->To(userId: 123, sum: 50.00)
    ->Comment(
        userId: 123,
        plus: 50.00,
        comment: 'Бонус за активацию',
        plugin_name: 'activation',
        email: true
    );

// Списать за услугу
$balance->Check(userId: 123, sum: 30.00);
$balance->From(userId: 123, sum: 30.00)
    ->Comment(
        userId: 123,
        minus: 30.00,
        comment: 'Оплата услуги',
        plugin_name: 'service'
    );

Транзакция с переводом средств

$balance = \Billing\Api\Balance::Init();

$balance->Transaction();
try {
    $balance->From(userId: 123, sum: 100.00);
    $balance->To(userId: 456, sum: 100.00);

    $balance->Comment(userId: 123, minus: 100.00, comment: 'Перевод пользователю 456');
    $balance->Comment(userId: 456, plus: 100.00, comment: 'Перевод от пользователя 123');

    $balance->Commit();
} catch (\Exception $e) {
    $balance->Rollback();
    throw $e;
}

Создание счета с проверкой дубликатов

$balance = \Billing\Api\Balance::Init();
$balance->checkDouble(true);

$invoiceId = $balance->createInvoice(
    userId: 123,
    payment: 'qiwi',
    sum_get: 0,
    sum_pay: 250.00,
    payer_info: ['phone' => '+79001234567'],
    handler: 'qiwi_handler'
);

Зависимости

DLE (DataLife Engine) — основная система
\Billing\BalanceException — класс исключений
\Billing\Hooks — интерфейс для плагинов
\Billing\Api\Message — внутренняя почта
\Billing\Api\Email — email уведомления

Документация сгенерирована автоматически из кода класса Billing\Api\Balance