Керуйте тарифними планами та лімітами в Laravel за допомогою Laravel Entitlements

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

Замість розробки власної логіки з нуля, ви отримуєте структурований підхід, побудований навколо планів, ліцензій та відстеження споживання ресурсів. Основні можливості пакета:

• Слот-орієнтоване та пулове споживання — стратегія слотів відстежує використання для конкретних об'єктів (наприклад, пристрою чи робочого місця), тоді як пулова стратегія списує одиниці зі спільного лічильника (наприклад, AI tokens або API-кредити).
• Поліморфне володіння — будь-яка Eloquent модель може стати підписником за допомогою трейту HasEntitlements. Це дозволяє легко налаштовувати права для команд, робочих просторів або окремих користувачів.
• Каталог тарифів з опціями білінгу — плани підтримують місячні та річні цикли, можуть бути регулярними або фіксованими, а також дозволяють перевизначати кількість ресурсів для окремих призначень.
• Доменні події — пакет генерує події на кшталт LicenseConsumed, ReleaseRequested та LicenseReconciled, що спрощує інтеграцію з білінг-вебхуками, фоновими завданнями або системами аудиту.
• Адмін-панель Filament v5 (опціонально) — готовий інтерфейс для керування планами, категоріями та ліцензіями, який можна інтегрувати у ваш проєкт на Filament.

# Визначення типів прав

Пакет використовує PHP backed enum для визначення типів прав та їхніх стратегій. Це дозволяє прив'язати логіку споживання до доменної логіки вашого додатка, а не до загальних конфігурацій:

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(),
        };
    }
}

Опція twoPhase: true для типу Device заслуговує на увагу: вона розділяє вивільнення ресурсу на два етапи (requestRelease() та confirmRelease()). Це корисно, коли потрібно дочекатися завершення зовнішнього процесу (наприклад, анулювання токена пристрою) перед звільненням слота.

# Використання та перевірка прав

Після призначення плану підписнику споживання ресурсу виконується одним викликом методу:

// Слот-система: прив’язка використання до конкретного об’єкта
Entitlements::consume($workspace, LicenseType::Seat, $user);
 
// Пулова система: списання обсягу зі спільного лічильника
Entitlements::consume($workspace, LicenseType::AiTokens, $usage, amount: 1500);

Перевірка доступності ресурсів здійснюється так само просто:

Entitlements::can($workspace, LicenseType::AiTokens, 1500); // bool
Entitlements::available($workspace, LicenseType::AiTokens); // залишок ліміту

Якщо ліміт вичерпано, пакет викидає виняток NoEntitlementAvailableException, який можна обробити на рівні контролера або middleware.

# Зміна тарифних планів

Перехід підписника між планами реалізовано через метод changePlan(), що підтримує як миттєву зміну, так і перехід наприкінці розрахункового періоду. Пакет валідує транзицію перед збереженням, гарантуючи, що користувачі не втратять доступ до вже активованих ресурсів при переході на дешевший тариф.

# Встановлення

Встановіть пакет через 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 потребує версії v5.

Повна документація та вихідний код доступні на GitHub.