Laravel Model Caching

Relationship-aware Eloquent model caching for Laravel.

This package is designed for applications where cached parent queries must be invalidated when loaded child models change. It is not only a query cache. It stores deterministic query results and records a lightweight dependency index from model instances to cache keys.

Features

Opt-in model caching through HasModelCaching
remember(), rememberForever(), dontCache(), and optional auto_remember for trait-enabled models
Cached read operations: get, first, firstOrFail, find, findOrFail, and pagination methods
Nested eager-load aware cache keys
Pagination-safe keys for paginate(), simplePaginate(), and cursorPaginate()
Morph map versioning in cache keys
Dependency index for precise invalidation on child updates
Structured cache payloads for models and collections (safe for morph relations and eager loads)
Cache tags when the selected Laravel cache driver supports them
Model observer invalidation for saved, deleted, restored, and force deleted events
Artisan commands for warming, inspecting, and flushing tracked entries

Installation

composer require ghostcompiler/laravel-model-caching

Publish the config:

php artisan vendor:publish --tag=model-cache-config

Redis is recommended for production because the dependency index can use native Redis sets.

Quick Start

Add the trait to models that should be cacheable:

use GhostCompiler\LaravelModelCaching\Concerns\HasModelCaching;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use HasModelCaching;
}

The trait alone does not cache queries. Either call remember() on the chain or enable auto_remember in config.

Use remember() on normal Eloquent queries:

$users = User::with('posts.comments')
    ->where('active', true)
    ->remember(60)
    ->get();

$tenant = User::whereHas('brand.domains', fn ($q) => $q->where('domain', $host))
    ->with('brand')
    ->remember(300)
    ->firstOrFail();

Enable automatic caching for all read queries on trait-enabled models:

// config/model-cache.php
'auto_remember' => true,

Then User::where('active', true)->first() is cached with default_ttl. Use dontCache() on chains that must always hit the database.

Use the convenience APIs:

$user = User::findCached(1);

$user->loadCached('posts.comments');

Disable caching on a query chain:

$users = User::remember(600)
    ->dontCache()
    ->where('active', true)
    ->get();

Cache Key Safety

Each key includes:

Model class, table, and connection
SQL and bindings
Selected columns
Limit, offset, groups, and orders
Eager loads, including nested relation names
Closure constraint source fingerprints when available
Pagination page, page name, cursor, and per-page values
Morph map and configured morph map version
Optional auth and tenant context

These queries generate different keys:

User::with('posts')->remember(60)->get();
User::with('posts.comments')->remember(60)->get();
User::with(['posts', 'roles'])->remember(60)->get();

Dependency Invalidation

On a cache miss, the package stores the query result and walks the returned models plus loaded relations. It records only model primary keys in a dependency index:

model-cache:dependency:user:1 -> [cache-key-a]
model-cache:dependency:post:5 -> [cache-key-a, cache-key-b]
model-cache:dependency:comment:9 -> [cache-key-b]

When Post #5 is saved, deleted, or force deleted, only keys listed under model-cache:dependency:post:5 are forgotten. No full application cache flush is required.

When a new Post is created (or soft-deleted row is restored), every cached query rooted on that model class is forgotten too — for example paginated user lists — so new rows can appear on the next request without waiting for TTL expiry:

model-cache:dependency:user:{class-hash}:_class -> [page-1-key, page-2-key, ...]

Updates to an existing row still invalidate only that row's dependencies plus any list page that included that instance.

Cache tags are used as an extra layer when supported. Per-entry tag metadata is stored separately so entries can include result-specific tags such as post:5 while still being readable later from a deterministic query key.

Morph Relations

Polymorphic relations are supported through the actual related models returned by Eloquent and through morph context in the cache key. If you change Laravel's morph map aliases, bump:

'morph_map_version' => 2,

This prevents old entries from colliding with new alias meanings.

Pagination

Pagination methods are cached at the top-level builder operation:

$users = User::with('posts')->remember(300)->paginate(10);

The key includes the page name, current page, per-page value, and cursor state where applicable.

Configuration

return [
    'enabled' => true,
    'default_ttl' => 3600,
    'auto_remember' => false,
    'store' => null,
    'prefix' => 'model-cache',
    'cache_tags' => true,
    'dependency_ttl' => 604800,
    'use_redis_sets' => true,
    'auto_observe_models' => true,
    'include_auth_id' => false,
    'context_callbacks' => [],
    'morph_map_version' => 1,
    'debug' => false,
];

For multi-tenant apps, add a context callback:

'context_callbacks' => [
    'tenant' => fn () => tenant('id'),
],

Commands

Warm a query:

php artisan model-cache:warm "App\Models\User" --with=posts --with=posts.comments --ttl=600 --limit=1000

Inspect keys depending on a model instance:

php artisan model-cache:inspect "App\Models\Post" 5

Flush keys depending on a model instance:

php artisan model-cache:flush "App\Models\Post" 5

Flush every key known to the package dependency index:

php artisan model-cache:flush --known

Production Notes

Treat auto_remember carefully: incidental reads on cacheable models are cached until TTL or model invalidation. Use dontCache() in admin or debug paths.
Prefer Redis for high traffic APIs.
Keep cacheable queries deterministic.
Include tenant/auth context when query results differ by user or tenant.
Use eager loading intentionally. The package tracks loaded relations, not unloaded graph possibilities.
Bump morph_map_version after morph map changes.
Use rememberForever() only for data that is always invalidated by model events.

Testing

composer install
composer test

Development And Build Environment

This package was developed using ServBay as the local development environment.

Development Tool Used

Local development tool: ServBay
Website: www.servbay.com

ServBay your development friend

Testing And Build Machine

Tested on: Mac M4
Built on: Mac M4

Files main

Repository Files

Loading file structure...

src/Cache/DependencyTracker.php

<?php

namespace GhostCompiler\LaravelModelCaching\Cache;

use Illuminate\Database\Eloquent\Collection as EloquentCollection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Pagination\AbstractPaginator;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;
use Throwable;

class DependencyTracker
{
    /**
     * @param  array<int, string>  $tags
     */
    public function track(string $cacheKey, mixed $value, array $tags, int|null $ttl = null, Model|null $queryModel = null): void
    {
        $dependencies = $this->extractDependencies($value);

        if ($queryModel !== null) {
            $dependencies[] = $this->classDependencyKey($queryModel);
        }

        $dependencies = array_values(array_unique($dependencies));
        $ttl ??= (int) config('model-cache.dependency_ttl', 604800);

        $this->putArray($this->metaKey($cacheKey), [
            'tags' => array_values(array_unique($tags)),
            'dependencies' => $dependencies,
        ], $ttl);

        $this->addToSet($this->allKeysKey(), $cacheKey, $ttl);

        foreach ($dependencies as $dependency) {
            $this->addToSet($dependency, $cacheKey, $ttl);
        }
    }

    /**
     * @return array<int, string>
     */
    public function tagsForCacheKey(string $cacheKey): array
    {
        $meta = Cache::store(config('model-cache.store'))->get($this->metaKey($cacheKey), []);

        return is_array($meta) && isset($meta['tags']) && is_array($meta['tags'])
            ? $meta['tags']
            : [];
    }

    public function invalidateModel(Model $model): int
    {
        $dependency = $this->dependencyKey($model);
        $cacheKeys = $this->members($dependency);
        $count = 0;

        foreach ($cacheKeys as $cacheKey) {
            $this->forgetCacheKey($cacheKey);
            $count++;
        }

        $this->forgetSet($dependency);

        return $count;
    }

    public function invalidateClassQueries(Model|string $model): int
    {
        $dependency = $this->classDependencyKey($model);
        $cacheKeys = $this->members($dependency);
        $count = 0;

        foreach ($cacheKeys as $cacheKey) {
            $this->forgetCacheKey($cacheKey);
            $count++;
        }

        $this->forgetSet($dependency);

        return $count;
    }

    public function flushKnownCacheKeys(): int
    {
        $keys = $this->members($this->allKeysKey());
        $count = 0;

        foreach ($keys as $cacheKey) {
            $this->forgetCacheKey($cacheKey);
            $count++;
        }

        $this->forgetSet($this->allKeysKey());

        return $count;
    }

    /**
     * @return array<int, string>
     */
    public function cacheKeysForModel(Model $model): array
    {
        return $this->members($this->dependencyKey($model));
    }

    /**
     * @return array<int, string>
     */
    public function cacheKeysForClass(Model|string $model): array
    {
        return $this->members($this->classDependencyKey($model));
    }

    protected function forgetCacheKey(string $cacheKey): void
    {
        $repository = Cache::store(config('model-cache.store'));
        $meta = $repository->get($this->metaKey($cacheKey), []);
        $tags = is_array($meta) && is_array($meta['tags'] ?? null) ? $meta['tags'] : [];
        $dependencies = is_array($meta) && is_array($meta['dependencies'] ?? null) ? $meta['dependencies'] : [];

        try {
            if ($tags !== []) {
                $repository->tags($tags)->forget($cacheKey);
            } else {
                $repository->forget($cacheKey);
            }
        } catch (Throwable) {
            $repository->forget($cacheKey);
        }

        foreach ($dependencies as $dependency) {
            $this->removeFromSet((string) $dependency, $cacheKey);
        }

        $this->removeFromSet($this->allKeysKey(), $cacheKey);
        $repository->forget($this->metaKey($cacheKey));
    }

    /**
     * @return array<int, string>
     */
    protected function extractDependencies(mixed $value): array
    {
        $dependencies = [];
        $seen = [];

        $this->walk($value, $dependencies, $seen);

        return array_values(array_unique($dependencies));
    }

    /**
     * @param  array<int, string>  $dependencies
     * @param  array<string, bool>  $seen
     */
    protected function walk(mixed $value, array &$dependencies, array &$seen): void
    {
        if ($value instanceof Model) {
            $objectId = spl_object_hash($value);

            if (isset($seen[$objectId])) {
                return;
            }

            $seen[$objectId] = true;

            if ($value->exists && $value->getKey() !== null) {
                $dependencies[] = $this->dependencyKey($value);
            }

            foreach ($value->getRelations() as $relationValue) {
                $this->walk($relationValue, $dependencies, $seen);
            }

            return;
        }

        if ($value instanceof AbstractPaginator) {
            $this->walk($value->getCollection(), $dependencies, $seen);

            return;
        }

        if ($value instanceof EloquentCollection || $value instanceof Collection || is_array($value)) {
            foreach ($value as $item) {
                $this->walk($item, $dependencies, $seen);
            }
        }
    }

    protected function dependencyKey(Model $model): string
    {
        return $this->dependencyKeyForClass($model::class).':'.$model->getKey();
    }

    protected function classDependencyKey(Model|string $model): string
    {
        $class = $model instanceof Model ? $model::class : $model;

        return $this->dependencyKeyForClass($class).':_class';
    }

    protected function dependencyKeyForClass(string $class): string
    {
        $prefix = trim((string) config('model-cache.prefix', 'model-cache'), ':');
        $alias = Str::of(class_basename($class))->snake()->replace('\\', '_')->toString();
        $classHash = substr(hash('xxh128', $class), 0, 12);

        return "{$prefix}:dependency:{$alias}:{$classHash}";
    }

    protected function metaKey(string $cacheKey): string
    {
        return trim((string) config('model-cache.prefix', 'model-cache'), ':').':meta:'.hash('sha256', $cacheKey);
    }

    protected function allKeysKey(): string
    {
        return trim((string) config('model-cache.prefix', 'model-cache'), ':').':keys';
    }

    /**
     * @param  array<mixed>  $value
     */
    protected function putArray(string $key, array $value, int $ttl): void
    {
        Cache::store(config('model-cache.store'))->put($key, $value, $ttl);
    }

    protected function addToSet(string $key, string $member, int $ttl): void
    {
        if ($this->redisCommand('sadd', [$key, $member]) !== false) {
            $this->redisCommand('expire', [$key, $ttl]);
            Cache::store(config('model-cache.store'))->put($key.':ttl', true, $ttl);

            return;
        }

        $members = Cache::store(config('model-cache.store'))->get($key, []);
        $members = is_array($members) ? $members : [];
        $members[] = $member;

        Cache::store(config('model-cache.store'))->put($key, array_values(array_unique($members)), $ttl);
    }

    /**
     * @return array<int, string>
     */
    protected function members(string $key): array
    {
        $redisMembers = $this->redisCommand('smembers', [$key]);

        if (is_array($redisMembers)) {
            return array_map('strval', $redisMembers);
        }

        $members = Cache::store(config('model-cache.store'))->get($key, []);

        return is_array($members) ? array_map('strval', $members) : [];
    }

    protected function removeFromSet(string $key, string $member): void
    {
        if ($this->redisCommand('srem', [$key, $member]) !== false) {
            return;
        }

        $members = Cache::store(config('model-cache.store'))->get($key, []);

        if (! is_array($members)) {
            return;
        }

        Cache::store(config('model-cache.store'))->put($key, array_values(array_diff($members, [$member])), (int) config('model-cache.dependency_ttl', 604800));
    }

    protected function forgetSet(string $key): void
    {
        if ($this->redisCommand('del', [$key]) !== false) {
            return;
        }

        Cache::store(config('model-cache.store'))->forget($key);
    }

    /**
     * @param  array<int, mixed>  $arguments
     */
    protected function redisCommand(string $command, array $arguments): mixed
    {
        if (! config('model-cache.use_redis_sets', true)) {
            return false;
        }

        try {
            $store = Cache::store(config('model-cache.store'))->getStore();

            if (! method_exists($store, 'connection')) {
                return false;
            }

            return $store->connection()->command($command, $arguments);
        } catch (Throwable) {
            return false;
        }
    }
}