‏Laravel Quota؛ سهمیهٔ مصرف کاربر رو تقویمی بشمار

پل ردموند تو Laravel News پکیجی به اسم Laravel Quota رو معرفی کرده که کارش دنبال کردن و اعمال محدودیت‌های مصرف انباشته‌ست. نمونه‌هاش دقیقاً همون چیزهاییه که تو محصولات SaaS می‌بینی: ۵۰ خروجی PDF در ماه، ۱۰۰۰ کوئری API در روز، یا یه استخر اعتبار هوش مصنوعی به ازای هر دورهٔ صورت‌حساب.

نویسنده تأکید می‌کنه این پکیج مسئلهٔ متفاوتی از RateLimiter خود لاراول رو حل می‌کنه. RateLimiter تو یه پنجرهٔ لغزان جلوی هجوم درخواست‌ها رو می‌گیره، ولی اینجا مصرف در برابر یه بودجه شمرده می‌شه که سر یه مرز تقویمی ریست می‌شه — و برخلاف کش، می‌تونه تو دیتابیس هم بمونه.

سهمیه در عمل یه شمارندهٔ نام‌داره که به یه مالک وصله، با یه سقف و یه دوره. بازه‌ها از perMinute() تا perYear() و حتی period($start, $end) دلخواه رو پوشش می‌دن:

$builder = Quota::for('api_queries', $user)
    ->limit(1000)
    ->perDay();

$builder->remaining();
$info = $builder->consume(5);

متد consume() یه DTO تغییرناپذیر به اسم QuotaInfo برمی‌گردونه. اگه ترجیح می‌دی به‌جای شرط گذاشتن، کار با خطا قطع بشه، enforce() وقتی بودجه تموم شده خطای HTTP 429 پرت می‌کنه. برای کارهایی که خرج دوباره توشون واقعاً دردسرسازه، block() کل کالبک رو داخل یه قفل اجرا می‌کنه تا دو درخواست هم‌زمان از چک ظرفیت رد نشن.

با trait به اسم HasQuotas همین سازنده از خود مدل الکوئنت آویزون می‌شه و می‌تونی مثلاً بنویسی $user->quota('pdf_exports'). رو درایور دیتابیس رکوردها پلی‌مورفیک ذخیره می‌شن، پس سهمیه‌های یه مدل رو مثل هر رابطهٔ دیگه‌ای کوئری می‌کنی.

یه میدل‌ور روت هم داره، به شکل quota:exports,50,month. نویسنده به یه نکتهٔ ظریفِ ترتیب اشاره می‌کنه: ظرفیت قبل از اجرای روت چک می‌شه ولی مصرف فقط وقتی ثبت می‌شه که پاسخ ۲xx یا ۳xx برگرده — یعنی درخواستی که ارور ۵۰۰ می‌ده یا اعتبارسنجی‌اش رد می‌شه، چیزی از سهمیهٔ کاربر کم نمی‌کنه.

درایور پیش‌فرض کشه (روی Redis و Memcached کار می‌کنه) ولی درایور database رو یه جدول quotas می‌نویسه؛ همون چیزی که وقتی شمارش به صورت‌حساب وصله لازم داری تا با پاک شدن کش بخار نشه. پکیج به PHP 8.2 نیاز داره و از لاراول ۱۱، ۱۲ و ۱۳ پشتیبانی می‌کنه.

نکات کلیدی:

• بودجهٔ مصرف تقویمی، از perMinute() تا perYear() و بازهٔ دلخواه
• consume() برای شمردن، enforce() برای پرت کردن خطای ۴۲۹ و block() برای مصرف اتمیک
• trait به اسم HasQuotas سهمیه رو روی هر مدل الکوئنت سوار می‌کنه
• میدل‌ور روت فقط روی پاسخ موفق مصرف رو ثبت می‌کنه
• درایور کش برای سرعت و درایور دیتابیس برای شمارش‌های مرتبط با صورت‌حساب