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/CacheValueSerializer.php

<?php

namespace GhostCompiler\LaravelModelCaching\Cache;

use BackedEnum;
use DateTimeInterface;
use Illuminate\Database\Eloquent\Collection as EloquentCollection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Pagination\AbstractCursorPaginator;
use Illuminate\Pagination\AbstractPaginator;
use Illuminate\Support\Collection;
use UnitEnum;

class CacheValueSerializer
{
    private const VERSION = 1;

    public function prepareForStorage(mixed $value): mixed
    {
        $encoded = $this->encode($value);

        if ($encoded !== null) {
            return $encoded;
        }

        return [
            '__mc_version' => self::VERSION,
            'type' => 'native',
            'payload' => base64_encode(serialize($value)),
        ];
    }

    public function restoreFromStorage(mixed $stored): mixed
    {
        if ($this->isCorrupt($stored)) {
            return null;
        }

        if (is_array($stored) && ($stored['__mc_version'] ?? null) === self::VERSION) {
            if (($stored['type'] ?? '') === 'native') {
                return $this->unserializeNative($stored['payload'] ?? '');
            }

            return $this->decode($stored);
        }

        return $this->restoreLiveValue($stored);
    }

    public function isCorrupt(mixed $value): bool
    {
        if (is_array($value)) {
            foreach ($value as $item) {
                if ($this->isCorrupt($item)) {
                    return true;
                }
            }

            return false;
        }

        if (! is_object($value)) {
            return false;
        }

        if (get_class($value) === '__PHP_Incomplete_Class') {
            return true;
        }

        if ($value instanceof Model) {
            foreach ($value->getRelations() as $relation) {
                if ($this->isCorrupt($relation)) {
                    return true;
                }
            }

            return false;
        }

        if ($value instanceof EloquentCollection || $value instanceof Collection) {
            foreach ($value as $item) {
                if ($this->isCorrupt($item)) {
                    return true;
                }
            }
        }

        if ($value instanceof AbstractPaginator || $value instanceof AbstractCursorPaginator) {
            return $this->isCorrupt($value->getCollection());
        }

        return false;
    }

    protected function encode(mixed $value): ?array
    {
        if ($value === null || is_scalar($value)) {
            return [
                '__mc_version' => self::VERSION,
                'type' => 'scalar',
                'value' => $value,
            ];
        }

        if ($value instanceof Model) {
            $attributes = $this->normalizeForStorage($value->getAttributes());

            return [
                '__mc_version' => self::VERSION,
                'type' => 'model',
                'class' => $value::class,
                'connection' => $value->getConnectionName(),
                'attributes' => $attributes,
                'original' => $this->normalizeForStorage($value->getOriginal()),
                'exists' => $value->exists,
                'was_recently_created' => $value->wasRecentlyCreated,
                'relations' => $this->encodeRelations($value->getRelations()),
            ];
        }

        if ($value instanceof EloquentCollection) {
            return [
                '__mc_version' => self::VERSION,
                'type' => 'eloquent_collection',
                'items' => array_map(fn (mixed $item) => $this->prepareForStorage($item), $value->all()),
            ];
        }

        if ($value instanceof Collection) {
            return [
                '__mc_version' => self::VERSION,
                'type' => 'collection',
                'items' => array_map(fn (mixed $item) => $this->prepareForStorage($item), $value->all()),
            ];
        }

        return null;
    }

    /**
     * @param  array<string, mixed>  $relations
     * @return array<string, mixed>
     */
    protected function encodeRelations(array $relations): array
    {
        $encoded = [];

        foreach ($relations as $name => $relation) {
            $encoded[$name] = $this->prepareForStorage($relation);
        }

        return $encoded;
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function decode(array $payload): mixed
    {
        return match ($payload['type'] ?? '') {
            'scalar' => $payload['value'] ?? null,
            'model' => $this->decodeModel($payload),
            'eloquent_collection' => $this->decodeEloquentCollection($payload),
            'collection' => $this->decodeCollection($payload),
            default => null,
        };
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function decodeModel(array $payload): Model
    {
        /** @var class-string<Model> $class */
        $class = $payload['class'];

        /** @var Model $model */
        $model = (new $class)->newFromBuilder(
            $payload['attributes'] ?? [],
            $payload['connection'] ?? null,
        );
        $model->exists = (bool) ($payload['exists'] ?? true);
        $model->syncOriginal($payload['original'] ?? $payload['attributes'] ?? []);
        $model->wasRecentlyCreated = (bool) ($payload['was_recently_created'] ?? false);

        foreach ($payload['relations'] ?? [] as $name => $relation) {
            $decoded = $this->restoreFromStorage($relation);

            if ($decoded !== null) {
                $model->setRelation((string) $name, $decoded);
            }
        }

        return $model;
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function decodeEloquentCollection(array $payload): EloquentCollection
    {
        $items = [];

        foreach ($payload['items'] ?? [] as $item) {
            $decoded = $this->restoreFromStorage($item);

            if ($decoded instanceof Model) {
                $items[] = $decoded;
            }
        }

        return new EloquentCollection($items);
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function decodeCollection(array $payload): Collection
    {
        $items = [];

        foreach ($payload['items'] ?? [] as $item) {
            $decoded = $this->restoreFromStorage($item);
            $items[] = $decoded;
        }

        return collect($items);
    }

    protected function restoreLiveValue(mixed $value): mixed
    {
        if ($value instanceof Model) {
            return $this->rehydrateModel($value);
        }

        if ($value instanceof EloquentCollection) {
            return new EloquentCollection(
                $value
                    ->map(fn (mixed $item) => $this->restoreLiveValue($item))
                    ->filter(fn (mixed $item) => $item instanceof Model)
                    ->all()
            );
        }

        if ($value instanceof Collection) {
            return $value->map(fn (mixed $item) => $this->restoreLiveValue($item));
        }

        if ($value instanceof AbstractPaginator || $value instanceof AbstractCursorPaginator) {
            $value->setCollection(
                $this->restoreLiveValue($value->getCollection())
            );

            return $value;
        }

        return $value;
    }

    protected function rehydrateModel(Model $model): Model
    {
        $class = $model::class;

        /** @var Model $fresh */
        $fresh = (new $class)->newFromBuilder($model->getAttributes(), $model->getConnectionName());
        $fresh->exists = $model->exists;
        $fresh->syncOriginal($model->getOriginal());
        $fresh->wasRecentlyCreated = $model->wasRecentlyCreated;

        foreach ($model->getRelations() as $name => $relation) {
            $fresh->setRelation((string) $name, $this->restoreLiveValue($relation));
        }

        return $fresh;
    }

    protected function unserializeNative(string $payload): mixed
    {
        if ($payload === '') {
            return null;
        }

        $decoded = base64_decode($payload, true);

        if ($decoded === false) {
            return null;
        }

        $value = @unserialize($decoded, ['allowed_classes' => true]);

        if ($this->isCorrupt($value)) {
            return null;
        }

        return $this->restoreLiveValue($value);
    }

    /**
     * @param  array<string, mixed>  $values
     * @return array<string, mixed>
     */
    protected function normalizeForStorage(array $values): array
    {
        $normalized = [];

        foreach ($values as $key => $value) {
            $normalized[$key] = $this->normalizeValueForStorage($value);
        }

        return $normalized;
    }

    protected function normalizeValueForStorage(mixed $value): mixed
    {
        if ($value === null || is_scalar($value)) {
            return $value;
        }

        if ($value instanceof DateTimeInterface) {
            return $value->format(DateTimeInterface::ATOM);
        }

        if ($value instanceof BackedEnum) {
            return $value->value;
        }

        if ($value instanceof UnitEnum) {
            return $value->name;
        }

        if (is_array($value)) {
            return $this->normalizeForStorage($value);
        }

        if ($value instanceof Collection) {
            return $value
                ->map(fn (mixed $item) => $this->normalizeValueForStorage($item))
                ->all();
        }

        if (is_object($value)) {
            if (method_exists($value, '__toString')) {
                return (string) $value;
            }

            if (method_exists($value, 'toArray')) {
                /** @var array<string, mixed> $array */
                $array = $value->toArray();

                return $this->normalizeForStorage($array);
            }
        }

        return $value;
    }
}