README

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

نصب

# Laravel 13
composer require karnoweb/smart-cache:^13.0

# Laravel 10–12
composer require karnoweb/smart-cache:^1.0

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

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)

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

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

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

در مقایسه با پکیج‌هایی مثل 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 تهاجمی کمتر شود.

نیازمندی‌ها

لایسنس

MIT