Download the PHP package kai-init/laravel-normcache without Composer

Laravel Normcache

Normalized, self-invalidating Redis caching for Laravel Eloquent.

Normcache caches model-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+

Table of Contents

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

Installation

Add Cacheable to models you want Normcache to manage:

What's new in v3

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:

Use withoutCache() or ttl() per query:

Cross-table queries

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

For other cross-table reads, declare dependencies explicitly:

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:

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

Tags can group query entries for manual flushing:

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:

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:

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:

Configuration

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

Common options:

Bypasses and limitations

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

Always bypassed:

• pessimistic locks (lockForUpdate, sharedLock)
• reads forced to the write connection with useWritePdo()
• reads inside a database transaction
• DB::table(...), DB::select(), and raw SQL

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 NormCache\Support\CacheKeyBuilder::reset() after switching tenants dynamically.

Observability

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

License

MIT