laravel-model-caching

The package provides automatic caching for Eloquent model queries and eager-loaded relationships. By adding a specific trait or extending a base class, you enable a layer that caches query results and automatically flushes relevant cache entries when models are created, updated, or deleted. This eliminates the need for manual cache key management and manual invalidation logic.

What is cached:

• Model queries: get, first, find, all, paginate, pluck, value, exists.
• Aggregations: count, sum, avg, min, max.
• Eager-loaded relationships (using with()).

What is NOT cached:

• Lazy-loaded relationships: Only relationships loaded via with() are cached. You must use with() to benefit from caching.
• Queries with select() clauses: Custom column selections bypass the cache.
• Queries inside transactions: Cache is not automatically flushed when a transaction commits. You must call flushCache() manually if needed.
• inRandomOrder() queries: Caching is automatically disabled for these queries to ensure varied results.

You can enable caching using one of two methods: adding the Cachable trait to your models or extending the CachedModel class.

Option 1: Use the Cachable trait (Recommended)

The recommended approach is to add the Cachable trait to an abstract base model that all your other models extend.

Option 2: Extend CachedModel

Alternatively, you can have your models extend GeneaLabs\LaravelModelCaching\CachedModel directly.

Note on User models: You can safely use the Cachable trait on the User model without conflicting with Laravel's authentication. However, ensure user updates are performed via Eloquent (not raw DB::table() queries) to ensure cache invalidation triggers correctly.

// Option 1: Using the Cachable trait in a base model
namespace App\Models;

use GeneaLabs\LaravelModelCaching\Traits\Cachable;
use Illuminate\Database\Eloquent\Model;

abstract class BaseModel extends Model
{
    use Cachable;
}

// Option 2: Extending CachedModel directly
namespace App\Models;

use GeneaLabs\LaravelModelCaching\CachedModel;

class Post extends CachedModel
{
    // ...
}

To use DynamoDB as a dedicated cache store, first define the store in config/cache.php using the dynamodb driver. Then, set MODEL_CACHE_STORE to your new store name.

Requirements:

• Install the AWS SDK: composer require aws/aws-sdk-php.
• Enable DynamoDB TTL on the expires_at attribute in your table.

Note on Invalidation: Invalidation on DynamoDB uses logical namespace versioning. modelCache:clear rotates a package-wide namespace key, making old rows unreachable. Rows are not physically deleted immediately; they are removed later via TTL.

When to use DynamoDB vs Redis:

• DynamoDB: Best for AWS-native/serverless environments or when you want a managed store without running Redis.
• Redis: Best for lower latency, higher write churn, native tag support, or faster physical cleanup.

MODEL_CACHE_STORE=dynamodb-model
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_DYNAMODB_CACHE_ENDPOINT=
AWS_DYNAMODB_CACHE_TABLE=cache

'stores' => [
    'dynamodb-model' => [
        'driver' => 'dynamodb',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'table' => env('AWS_DYNAMODB_CACHE_TABLE', 'cache'),
        'endpoint' => env('AWS_DYNAMODB_CACHE_ENDPOINT'),
        'attributes' => [
            'key' => 'key',
            'value' => 'value',
            'expiration' => 'expires_at',
        ],
    ],
],

To prevent frequent writes from immediately flushing the cache in high-traffic scenarios, you can implement a cool-down period. This requires two steps:

1. Declare the default duration on the model using the $cacheCooldownSeconds property.
2. Activate the cool-down in your query using withCacheCooldownSeconds().

Once activated, writes during the cool-down window will not flush the cache. After the window expires, the next write triggers a flush and re-warms the cache.

<?php

namespace App\Models;

use GeneaLabs\LaravelModelCaching\Traits\Cachable;
use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    use Cachable;

    protected $cacheCooldownSeconds = 300; // 5 minutes
}

// To activate using the model's default:
Comment::withCacheCooldownSeconds()->get();

// To override with a specific duration:
Comment::withCacheCooldownSeconds(30)->get();