‏Laravel Entitlements: مدیریت پلن و مجوزها در لاراول

پکیج Laravel Entitlements برای حل یکی از مسائل رایج در توسعه SaaS طراحی شده: اینکه هر مشترک دقیقاً چه کاری می‌تونه بکنه، چقدر می‌تونه مصرف کنه، و وقتی به سقف مصرف رسید یا پلنش رو عوض کرد چی می‌شه. به جای اینکه این منطق رو از صفر بنویسید، این پکیج یه ساختار آماده بر پایه پلن، لایسنس، و ردیابی مصرف بهتون می‌ده.

دو نوع استراتژی مصرف وجود داره: slot-based که مصرف رو به یه موجودیت مشخص (مثلاً یه دستگاه یا یه کاربر/صندلی) وصل می‌کنه، و pool-based که از یه مخزن مشترک کم می‌کنه (مثل توکن‌های AI یا اعتبار API). هر مدل Eloquent با اضافه کردن trait مربوطه می‌تونه subscriber بشه، یعنی می‌شه entitlementها رو به تیم، workspace، یا کاربر مستقل وصل کرد.

نوع entitlementها با یه 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 جالبه — آزادسازی slot رو به دو مرحله تقسیم می‌کنه (requestRelease و confirmRelease)؛ مفیده وقتی باید یه پروسه خارجی مثل لغو توکن دستگاه قبل از آزادشدن slot تموم بشه.

مصرف یه entitlement بعد از اختصاص پلن به subscriber، با یه متد انجام می‌شه:

// Slot-based: مصرف برای یه موجودیت مشخص
Entitlements::consume($workspace, LicenseType::Seat, $user);

// Pool-based: کم کردن از مخزن مشترک
Entitlements::consume($workspace, LicenseType::AiTokens, $usage, amount: 1500);

قبل از مصرف هم می‌شه با Entitlements::can() چک کرد که آیا ظرفیت کافیه یا نه، و با Entitlements::available() مقدار باقی‌مانده رو گرفت. اگه ظرفیت تموم بشه، پکیج یه NoEntitlementAvailableException پرتاب می‌کنه که می‌شه در controller یا middleware catch کرد.

پکیج رویدادهایی مثل LicenseConsumed، ReleaseRequested و LicenseReconciled رو dispatch می‌کنه که می‌شه ازشون برای webhook صورت‌حساب، job‌های پس‌زمینه یا audit log استفاده کرد. تغییر پلن هم از طریق changePlan() با پشتیبانی از تغییر فوری یا در پایان دوره انجام می‌شه. یه integration اختیاری با Filament v5 هم وجود داره که یه پنل مدیریت آماده برای پلن‌ها، دسته‌بندی‌ها و لایسنس‌ها فراهم می‌کنه.

نکات کلیدی:

• دو استراتژی مصرف: slot-based (مصرف به ازای موجودیت) و pool-based (مصرف از مخزن مشترک)
• هر مدل Eloquent می‌تونه با trait مربوطه subscriber بشه
• تعریف نوع entitlementها با PHP backed enum
• رویدادهای built-in برای ادغام با billing و سیستم‌های خارجی
• پشتیبانی از تغییر پلن فوری یا پایان‌دوره‌ای
• integration اختیاری با Filament v5
• نیاز به PHP 8.2+ و Laravel 11+