README

Normalized, self-invalidating Redis caching for Laravel Eloquent.

Normcache caches query results as ID lists and stores model attributes in versioned model keys. When a model changes, Normcache bumps a version key instead of scanning and deleting every query that may have returned that model.

Requirements: PHP 8.2+, Laravel 12/13, Redis 6.0+

Installation
What's new in 3.0
Usage
Invalidation
Cache spaces
Configuration
Bypasses and limitations
Observability
License

Installation

composer require kai-init/laravel-normcache

Add Cacheable to models you want Normcache to manage:

use Illuminate\Database\Eloquent\Model;
use NormCache\Traits\Cacheable;

class Post extends Model
{
    use Cacheable;
}

What's new in 3.0

Redis Cluster sharding is now fully atomic within each cache space. Normcache keeps the keys for a cached operation and its valid dependencies in one hash slot, so cache reads, rebuilds, and invalidation coordination remain atomic.

Cache spaces: declare $normCacheSpaces on a model and select a declared space with ->space() when needed.
Space-targeted flushing: use NormCache::flushAll('space') or php artisan normcache:flush --space=....
Named table dependencies: dependsOnTables() works in named spaces and is invalidated with invalidateTableVersion().
Upgrade from 2.4: run php artisan normcache:flush before deploying v3 to clear legacy cache keys.

Usage

Normal Eloquent reads are cached automatically for cacheable models:

Post::all();
Post::where('active', true)->get();
Post::find(1);
Post::paginate(20);

Use withoutCache() or ttl() per query:

Post::withoutCache()->get();
Post::where('active', true)->ttl(600)->get();

Cross-table queries

Simple whereHas / whereDoesntHave constraints on cacheable relations and plain string joins with an explicit root-table projection are inferred automatically:

Author::whereHas('posts', fn($q) => $q->where('published', true))->get();

Author::join('posts', 'posts.author_id', '=', 'authors.id')
    ->select('authors.*')
    ->get();

For other cross-table reads, declare dependencies explicitly:

Author::query()
    ->dependsOn([Post::class])
    ->get();

Author::join('legacy_stats', 'legacy_stats.author_id', '=', 'authors.id')
    ->select('authors.*')
    ->dependsOnTables(['legacy_stats'])
    ->get();

dependsOnTables() declares a read dependency only. If that table is changed outside Eloquent, call NormCache::invalidateTableVersion($connection, $table) after the write.

Aggregates and relationships

count, exists, value, pluck, sum, avg, min, max, pagination totals, and withCount / withSum / withAvg / withMin / withMax / withExists are cached when their dependencies are safe.

Eager-loaded BelongsTo, BelongsToMany, MorphTo, MorphToMany, MorphedByMany, HasManyThrough, and HasOneThrough relations are cached. attach, detach, sync, and updateExistingPivot invalidate the relevant pivot cache.

Invalidation

Eloquent writes on cacheable models invalidate automatically. For manual invalidation:

use NormCache\Facades\NormCache;

NormCache::flushModel(Post::class);
NormCache::flushAll();
NormCache::flushAll('content');

php artisan normcache:flush --model="App\Models\Post"
php artisan normcache:flush
php artisan normcache:flush --space=content

If you mutate cacheable tables outside Eloquent, flush the affected model or table version yourself:

DB::table('posts')->update(['published' => true]);
NormCache::flushModel(Post::class);

Tags can group query entries for manual flushing:

Author::whereHas('posts')
    ->dependsOn([Post::class])
    ->tag('homepage')
    ->get();

NormCache::flushTag(Author::class, 'homepage');
NormCache::flushTagAcrossModels('homepage');

Cache spaces

Cache spaces are Normcache's Redis Cluster sharding boundary. Each space has a Redis hash tag, so a cached operation stays within one Cluster slot.

Models without a declaration use the default space ({nc}). Declare named spaces with $normCacheSpaces:

use Illuminate\Database\Eloquent\Model;
use NormCache\Traits\Cacheable;

class Post extends Model
{
    use Cacheable;

    protected static array $normCacheSpaces = ['content'];
}

How space resolution works:

If no space() is selected, a model uses its first declared space as its home space.
Post::query()->space('content') explicitly selects a space.
space() must select a space declared by the model, otherwise Normcache throws an InvalidArgumentException.
A model may declare multiple spaces, up to spaces.max_per_model.
Writes bump the model version in every declared space.

Dependencies must belong to the active space:

class Author extends Model
{
    use Cacheable;

    protected static array $normCacheSpaces = ['content'];
}

Post::query()
    ->space('content')
    ->dependsOn([Author::class])
    ->get();

If a model dependency is not valid in the active space, Normcache bypasses the cache by default. Set spaces.cross_space_behavior to throw to fail loudly during development. Raw table dependencies from dependsOnTables() can be used in any active space and are invalidated with invalidateTableVersion().

Configure placement when you need to control Redis Cluster hash tags:

'spaces' => [
    'max_per_model' => 16,
    'cross_space_behavior' => env('NORMCACHE_CROSS_SPACE_BEHAVIOR', 'bypass'),
    'placement' => [
        'catalog' => ['hash_tag' => 'nc:catalog'],
    ],
],

Configuration

Publish config/normcache.php if you need to customize runtime behavior:

php artisan vendor:publish --tag=normcache-config

Common options:

Option	Purpose
`connection`	Redis connection name. Default: `cache`.
`enabled`	Master on/off switch.
`ttl`	Model attribute key lifetime.
`query_ttl`	Query/result/pivot/through key lifetime.
`key_prefix`	Prefix for all Normcache Redis keys.
`cooldown`	Debounce version bumps for write-heavy models.
`building_lock_ttl`	Cache rebuild lock lifetime.
`stampede_wait_ms`	How long waiters block for a rebuild wake signal.
`stampede_wake_tokens`	Number of waiters to wake after a rebuild.
`fallback`	Fail open to the database on Redis errors when `true`.
`events`	Dispatch cache hit/miss events when `true`.
`fire_retrieved`	Fire Eloquent `retrieved` for cached models when `true`.
`debugbar`	Enable Laravel Debugbar integration when installed.
`spaces.*`	Cache-space limits, cross-space policy, and hash-tag placement.

Bypasses and limitations

Normcache bypasses caching for unsafe reads rather than risking stale or incorrect data.

Always bypassed:

pessimistic locks (lockForUpdate, sharedLock)
reads inside a database transaction
DB::table(...), DB::select(), and raw SQL
chunk(), each(), lazy(), and sole()

Usually require dependsOn() or dependsOnTables():

manual whereExists
raw predicates
nested relation constraints
expression joins
GROUP BY, DISTINCT, and calculated columns

Other limitations:

Models should use standard single-column primary keys.
Writes outside Eloquent are invisible unless you manually flush or invalidate.
Packages that replace Eloquent builders, relation classes, or hydration behavior may bypass parts of Normcache.
Normcache caches model connection/table metadata. Call CacheKeyBuilder::reset() after switching tenants dynamically.

Observability

When events are enabled, Normcache dispatches query/model hit and miss events. When fruitcake/laravel-debugbar is installed and normcache.debugbar is enabled, cache hits, misses, bypasses, and model fetches appear in Debugbar.

License

MIT

kai-init / laravel-normcache

Maintainers

Package info

Statistics

Security