Laravel Entitlements для управления подписками и лимитами в Laravel

Пакет Laravel Entitlements решает одну из самых сложных задач в SaaS-приложениях: управление подписками, лицензиями, лимитами и отслеживанием использования функций. Вместо собственной реализации логики подписок пакет предлагает готовую структуру для работы с тарифами, лицензиями и потреблением ресурсов.

Пакет поддерживает два типа расходования лимитов:

• slot-based — один ресурс закрепляется за конкретным объектом, например устройством или пользователем;

• pool-based — используется общий пул ресурсов, например API-кредиты или AI-токены.

Также поддерживаются:

• полиморфные подписчики через trait HasEntitlements;

• тарифные планы с месячной и годовой оплатой;

• recurring и fixed-term подписки;

• события домена для интеграции с webhook и очередями;

• готовая админ-панель для Filament v5.

Определение типов лицензий

Для описания типов лицензий используется PHP enum с реализацией интерфейса EntitlementType.

enum LicenseType: string implements EntitlementType
{
    case Device = 'device';
    case AiTokens = 'ai_tokens';
    case Seat = 'seat';

    public function strategy(): EntitlementStrategy
    {
        return match ($this) {
            self::Device    => new SlotStrategy(twoPhase: true),
            self::AiTokens  => new PoolStrategy(),
            self::Seat      => new SlotStrategy(),
        };
    }
}

В примере:

• Device использует SlotStrategy с двухэтапным освобождением лицензии;

• AiTokens работает через общий пул ресурсов;

• Seat резервирует отдельный слот.
  

Опция twoPhase: true разделяет освобождение лицензии на два шага:

requestRelease();
confirmRelease();

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

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

После назначения плана подписчику использование лицензии сводится к одному вызову метода.

Slot-based пример:

Entitlements::consume($workspace, LicenseType::Seat, $user);

Pool-based пример:

Entitlements::consume(
    $workspace,
    LicenseType::AiTokens,
    $usage,
    amount: 1500
);

В первом случае лицензия закрепляется за конкретным пользователем. Во втором из общего пула списывается 1500 токенов.

Проверка доступных лимитов

Пакет позволяет проверить доступность ресурсов до их использования.

Entitlements::can(
    $workspace,
    LicenseType::AiTokens,
    1500
);

Метод возвращает bool.

Получение оставшегося лимита:

Entitlements::available(
    $workspace,
    LicenseType::AiTokens
);

Если лимит исчерпан, пакет выбрасывает исключение NoEntitlementAvailableException. Его можно обрабатывать в middleware или контроллерах.

Смена тарифного плана

Для переключения между тарифами используется метод changePlan().

Пакет поддерживает:

• мгновенную смену плана;

• переключение после окончания текущего периода.
  

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

Установка

Установка через Composer:

composer require masterix21/laravel-entitlements

Публикация конфигурации и миграций:

php artisan vendor:publish --tag="laravel-entitlements-config"

php artisan vendor:publish --tag="laravel-entitlements-migrations"

php artisan migrate

Пакет требует PHP 8.2+ и Laravel 11+. Для интеграции с Filament необходим Filament v5.

Laravel Entitlements дополняет инструменты вроде Laravel Cashier, которые отвечают за биллинг и Stripe-подписки, но не покрывают детальное управление entitlement-логикой внутри SaaS-приложения.