karnoweb/smart-cache

Model-aware smart caching for Laravel with automatic invalidation, tag support, and stampede protection.

v1.2.0 2026-02-14 07:48 UTC

Requires

• php: ^8.2
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• cache
• tags
• laravel
• model-cache
• smart-cache

README

کش وابسته به مدل برای لاراول با invalidation خودکار، پشتیبانی از تگ و محافظت در برابر cache stampede.

نصب

composer require karnoweb/smart-cache

استفادهٔ سریع

use Karnoweb\SmartCache\Facades\SmartCache;
use App\Models\User;

// ذخیره و خواندن
SmartCache::for(User::class)->key('features')->put($features);
$features = SmartCache::for(User::class)->key('features')->get();

// remember با محافظت در برابر stampede
$data = SmartCache::for(User::class)
    ->key('dashboard')
    ->remember(fn () => expensiveQuery());

با trait روی مدل:

use Karnoweb\SmartCache\Traits\HasModelCache;

class User extends Model
{
    use HasModelCache;
}

مستندات

مستندات به صورت ساختاریافته و قابل گسترش در پوشهٔ docs قرار دارد. برای فهرست کامل و دسترسی به همهٔ بخش‌ها به فایل زیر مراجعه کنید:

📚 فهرست مستندات (docs/0-index.md)

بخش‌های فعلی:

#	موضوع
1	نمای کلی — ویژگی‌ها و معماری
2	نصب و راه‌اندازی
3	پیکربندی
4	استفاده و API
5	جزئیات فنی — flush، race، TTL، stampede، محدودیت‌ها

برای افزودن مباحث جدید در آینده، فایل‌های شماره‌دار جدید (مثلاً 6-testing.md) را در docs اضافه کنید و لینک آن‌ها را در docs/0-index.md ثبت کنید.

مقایسه با سایر روش‌ها

ویژگی	Laravel Cache (خام)	Laravel Tagged Cache	Smart Cache
مدل‌محور	خیر — کلیدها دستی و پراکنده	خیر — تگ دستی	بله — کلیدها زیر prefix مدل
Flush به‌ازای «مدل»	خیر — باید کلیدها را بدانی	بله — با flush تگ	بله — SmartCache::for(User::class)->flush()
Auto-invalidation با رویداد مدل	خیر	خیر	بله (با trait و config)
Stampede protection در remember	خیر (خودت lock بزن)	خیر	بله (قابل قطع با config)
کار با File/Database (بدون تگ)	بله	خیر — فقط Redis/Memcached	بله — با RegistryDriver و lock در صورت پشتیبانی استور
ولیدیشن کلید	خیر	خیر	بله (طول، کاراکترهای ممنوع)
Default TTL متمرکز	از config کش	از config کش	از config پکیج (default_ttl)

در مقایسه با پکیج‌هایی مثل laravel-model-cache (کش خود Eloquent): Smart Cache کش «دلخواه» برای مدل است (هر کلید/مقداری)، نه فقط کش کردن خود کوئری/مدل؛ و invalidation فعلاً در سطح «کل مدل» است، نه per-record (گرانولار در نسخه‌های بعدی هدف است).

تست

composer install
./vendor/bin/phpunit

تست‌های واحد و یکپارچگی برای API، ولیدیشن کلید، RegistryDriver (array)، و یکپارچگی با Facade و استور array/file وجود دارد. برای جزئیات فنی (flush، race، stampede) به docs/5-technical-details.md مراجعه کنید.

قدم‌های بعدی (پیشنهادی)

• ورژن اولیه: برای ریپوهای تازه می‌توان با v0.1.0 تگ زد و به Packagist فرستاد تا نصب با composer require karnoweb/smart-cache بدون تعریف repository ممکن شود.
• Granular invalidation: در نسخه‌های بعد می‌توان invalidation به‌ازای رکورد (per-record) اضافه کرد تا به‌جای flush تمام کش مدل، فقط کلیدهای وابسته به همان رکورد پاک شوند و مشکل flush تهاجمی کمتر شود.

نیازمندی‌ها

• PHP 8.2+
• Laravel 10.x / 11.x / 12.x

لایسنس

MIT