thekaziomar / laravel-atomic-cache
Zero-headache, stampede-proof, and auto-invalidating caching for Laravel. Cache database queries in 2 lines without managing keys or observers.
Package info
github.com/kaziomarsh24/laravel-atomic-cache
pkg:composer/thekaziomar/laravel-atomic-cache
Requires
- php: ^8.2
- illuminate/cache: ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/console: ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/contracts: ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/database: ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/http: ^10.0 || ^11.0 || ^12.0 || ^13.0
- illuminate/support: ^10.0 || ^11.0 || ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^8.0 || ^9.0 || ^10.0 || ^11.0
- phpunit/phpunit: ^10.0 || ^11.0
Suggests
- ext-zlib: Required for payload gzip compression on large cache items.
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-14 09:20:15 UTC
README
High-Performance Caching & Invalidation Engine for Laravel
Eliminates cache stampedes using atomic distributed locks, auto-compresses large payloads (>50KB) by up to 70–80% (depending on payload structure), auto-partitions mega datasets across driver-safe chunks, brings zero-crash virtual tagging to File and Database drivers, and defers model cache invalidation to database transaction commits (
DB::afterCommit).
use App\Models\Product; use KaziOmar\AtomicCache\Facades\AtomicCache; // 1. Stampede Protection: 1,000 concurrent requests only run 1 query; others wait & read $report = AtomicCache::rememberWithLock('monthly_report', 3600, fn() => Report::generate()); // 2. Transaction-Safe Zero-Key Query Caching: auto-fingerprints SQL & auto-clears on commit $featured = Product::where('status', 'active')->latest()->atomicCache(3600);
Table of Contents
- Why Laravel Atomic Cache?
- Requirements & Installation
- Quickstart in 10 Seconds
- Architectural Philosophy: Core-First Caching
- Guarantees vs Non-Guarantees
- Layer 1: The Core Caching Engine (
AtomicCache::)- 1.1 Basic Caching
- 1.2 Stampede Protection (
rememberWithLock) - 1.3 Stale-While-Revalidate (
flexible) - 1.4 Virtual Tagging Engine (Native & Non-Taggable Stores)
- 1.5 Manual Cache Invalidation Methods
- 1.5 Automatic Payload Compression (Gzip)
- 1.6 Transparent Chunking (Mega Datasets & Collections)
- 1.7 Cache TTL Jitter (Thundering Herd Variance)
- 1.8 User-Scoped Caching (
rememberForUser) - 1.9 Write Deduplication (Cache DNA)
- 1.10 Optimistic Concurrency Control (OCC)
- 1.11 Self-Healing Engine
- 1.12 Transaction Guard (Active Database Transaction Bypass)
- Layer 2: Eloquent Model Lifecycle (
AutoClearsCache)- 2.1 Automatic Invalidation on
DB::afterCommit - 2.2 Declarative Parent Invalidation (
$cacheParents) - 2.3 Model-Level Manual Cache Flushing (
flushCache&clearCache) - 2.4 High-Frequency Update Columns (
$cacheIgnoreColumns) - 2.5 Strict Mode for Parent Relations (
strict_mode) - 2.6 Transaction-Safe Bulk Invalidation (
AtomicCache::invalidating) - 2.7 Critical Rules & What Breaks Model Auto-Invalidation
- 2.1 Automatic Invalidation on
- Layer 3: Query Builder Macros (
->atomicCache()) - Layer 4: Service & Repository Layer (
HasAtomicCache)- 4.1 Automatic Method-Level Caching (
$this->cache()) - 4.2 Pagination & Filter Isolation (
rememberCollection) - 4.3 Single Item Caching (
rememberItem/cacheItem) - 4.4 Service-Level Cache Invalidation Helpers
- 4.5 Query Parameter Sanitization & Whitelisting
- 4.6 DoS & Cache Poisoning Limits
- 4.7 Service Configuration Reference
- 4.8 Critical Rules & What Breaks Service Caching
- 4.1 Automatic Method-Level Caching (
- Layer 5: Blade Fragment Caching (
@atomicCache) - Layer 6: CLI Diagnostics & Auditing
- Driver Compatibility Matrix
- Configuration Reference
- Troubleshooting & FAQ
- Upgrade Guide
- Testing
- Credits & License
Why Laravel Atomic Cache?
| Feature | Standard Laravel Cache | Laravel Atomic Cache |
|---|---|---|
| Stampede Protection | No (All concurrent requests hit DB) | Atomic Lock (1 worker computes, others wait & read) |
| Large Payload Size | Raw uncompressed serialization | Auto Gzip (>50KB cuts Redis RAM by up to 70–80%) |
| Mega Datasets | Fails on 1MB Memcached / Redis freeze | Transparent Chunking (splits safely, preserves keys) |
| Redundant Writes | Every put hits storage/network | Write Deduplication (skips re-compression & chunk re-splitting) |
| Driver Tag Support | Crashes on File/Database stores | Virtual Tagging (works across all stores without Redis) |
| Corrupted Data | Throws crash exception to user | Self-Healing (cleans key, regenerates silently) |
| Simultaneous Expiry | All keys expire in same second | TTL Jitter (random variance prevents herd spikes) |
| Model Invalidation | Fragile observers before commit | DB::afterCommit (prevents transaction race conditions) |
| Query Caching | Manual key hashing required | Zero-Key Macros (auto SQL + eager load fingerprinting) |
| Architecture Audit | Manual DIY logging | Artisan Doctor CLI (atomic-cache:check) |
Requirements & Installation
- PHP:
8.2,8.3,8.4, or8.5 - Laravel Framework:
10.x,11.x,12.x, or13.x - PHP Extensions:
ext-zlib(optional for Gzip compression, enabled by default in 99% of PHP installs)
Install via Composer:
composer require thekaziomar/laravel-atomic-cache
Publish configuration (optional):
php artisan vendor:publish --tag="atomic-cache-config"
Quickstart in 10 Seconds
You can use Atomic Cache in two ways: via the Core Facade for explicit control, or via Model & Query Macros for declarative automation.
Approach A: Explicit Core Caching (Recommended)
use KaziOmar\AtomicCache\Facades\AtomicCache; // Tagged, stampede-proof caching across any store: $catalog = AtomicCache::tags(['products'])->rememberWithLock('active_products', 3600, function () { return Product::where('status', 'active')->get(); });
Approach B: Declarative Model & Query Automation
- In your Model: Add
use AutoClearsCache;namespace App\Models; use Illuminate\Database\Eloquent\Model; use KaziOmar\AtomicCache\Traits\AutoClearsCache; class Product extends Model { use AutoClearsCache; }
- In your Query: Chain
->atomicCache()$products = Product::where('status', 'active')->latest()->atomicCache(3600); $product = Product::where('slug', $slug)->atomicCacheFirst(3600);
- Audit your models:
php artisan atomic-cache:check
Architectural Philosophy: Core-First Caching
Laravel Atomic Cache is organized into a clean Core-First architecture:
┌────────────────────────────────────────────────────────────────────────┐
│ Optional Syntactic Sugar │
│ Query Macros Service Trait Blade Directives │
│ (->atomicCache()) (HasAtomicCache) (@atomicCache) │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────────────────────────▼────────────────────────────────────┐
│ Eloquent Model Lifecycle Layer │
│ (AutoClearsCache) │
│ created / updated / deleted / restored --> DB::afterCommit │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────────────────────────▼────────────────────────────────────┐
│ The Core Engine (AtomicCache::) │
│ Distributed Locks • Virtual Tags • Gzip Compression • OCC │
│ Transparent Chunking • Self-Healing • TTL Jitter • Cache DNA │
└────────────────────────────────────────────────────────────────────────┘
The Core Engine (AtomicCache::) is completely self-contained and explicit. While query macros and traits provide convenient shortcuts, you can build your entire application directly with the Core Engine for transparent and predictable control.
Guarantees vs Non-Guarantees
To ensure complete clarity on what the package handles automatically versus what requires developer attention:
| Scenario / Operation | Automated by Package? | Behavior / Action Required |
|---|---|---|
Eloquent Model Instance Save: $product->save(), update() |
Yes | Automatically flushes item tag (products:42), collection tag (products), and parent relations strictly on DB::afterCommit. |
Model Deletes & Restores: $product->delete(), restore() |
Yes | Automatically flushes related tags on DB::afterCommit. |
Model Counters: $product->increment(), decrement() |
Yes | Fires updated model event; automatically clears cache on commit. |
Single-Level BelongsTo Parents: $cacheParents = ['store'] |
Yes | Automatically clears child tag, scoped tag (stores:5:orders), and parent umbrella tag (stores:5). |
Rolled-back Transactions: DB::rollBack() |
Yes | Invalidation callbacks are deferred to afterCommit. If rollback occurs, cache is untouched. |
Query Builder Mass Updates: Product::where(...)->update(...) |
No | Eloquent events do not fire. You must manually call Product::flushCache(); or AtomicCache::clearCollection('products'). |
Query Builder Mass Deletes: Product::where(...)->delete(...) |
No | Eloquent events do not fire. Call Product::flushCache(); manually. |
Direct SQL / DB Facade: DB::table('products')->delete(...) |
No | Bypasses Eloquent entirely. Call AtomicCache::clearCollection('products') manually. |
Quiet Operations: saveQuietly(), withoutEvents() |
No | Intentionally suppresses model events. Call $product->clearCache() manually if needed. |
Pivot Table Changes: Many-to-many attach(), detach(), sync() |
No | Pivot mutations do not fire model events on parent models. Call AtomicCache::clearTags(...) manually. |
Multi-Level Grandparent Propagation: Item -> Order -> Store |
No | Laravel's native $touches property calls rawUpdate() which does not fire Eloquent model events. You must either manually invoke $orderItem->order->touch() in an observer/controller or declare explicit parent tags via getRelatedCacheTags(). |
| External Database Mutations: External scripts, DB triggers, ETL imports | No | External processes outside PHP cannot trigger Laravel events. Schedule or invoke cache invalidation manually. |
Layer 1: The Core Caching Engine (AtomicCache::)
The AtomicCache facade provides manual, high-performance caching with distributed concurrency controls.
1.1 Basic Caching
How it works:
Works intuitively like native Laravel cache, supporting flexible parameter ordering (both $ttl, $callback and $callback, $ttl):
use KaziOmar\AtomicCache\Facades\AtomicCache; // Standard signature: remember($key, $ttl, $callback) $posts = AtomicCache::remember('posts.all', 3600, function () { return Post::where('published', true)->get(); }); // Alternative signature: remember($key, $callback, $ttl) $posts = AtomicCache::remember('posts.all', fn() => Post::all(), 3600); // Global helper shortcut: $posts = atomic_cache('posts.all', fn() => Post::all(), 3600); // Standard CRUD operations: AtomicCache::put('site_settings', $settings, 86400); // Store directly $value = AtomicCache::get('site_settings'); // Retrieve $exists = AtomicCache::has('site_settings'); // Check existence $val = AtomicCache::pull('site_settings'); // Retrieve and delete AtomicCache::forget('site_settings'); // Delete single key
Parameters Reference:
| Parameter | Type | Description |
|---|---|---|
$key |
string |
Unique cache identifier in your cache store (e.g. 'posts.all', 'home.banners'). |
$ttl |
int|DateTimeInterface |
Time-to-live in seconds or future Carbon instance. If omitted, uses config('atomic-cache.default_ttl', 3600). |
$callback |
Closure |
Closure executed on cache miss to compute the value. |
What will break it / What causes it not to work properly:
- Passing a non-positive TTL (
0or negative number): CallingAtomicCache::put('key', $value, 0)will not cache the item; it immediately executesforget('key')and deletes the item. - Passing a past
DateTimeInterface: Passing a Carbon date in the past will calculate a negative TTL and immediately delete the key. - Un-serializable callback returns: If your closure returns an open resource (like a
curlhandle, file pointer, orPDOinstance), PHP serialization will fail and store an empty or corrupted entry.
1.2 Stampede Protection (rememberWithLock)
How it works:
When an expensive cache item expires under high traffic, dozens or hundreds of concurrent requests simultaneously execute the heavy database query (known as the Dogpiling or Cache Stampede effect).
rememberWithLock acquires an atomic distributed lock via Laravel's LockProvider. Only the first process calculates the value, while all other requests wait up to waitSeconds (default 5s) and read the freshly computed cache from memory using Double-Checked Locking:
$stats = AtomicCache::rememberWithLock('annual_sales_report', 86400, function () { return HeavyReportingService::calculate(); }, lockSeconds: 15, waitSeconds: 5);
What will break it / What causes it not to work properly:
- Using a cache store without lock support: Drivers that do not implement
Illuminate\Contracts\Cache\LockProvider(or thenulldriver whoseNullStorereturns a dummyNoLock) do not provide distributed concurrency locking. The engine safely detects unsupported lock providers and bypasses locking, executing the callback directly. (Note: Laravel'sredis,memcached,database, andfiledrivers all support locks natively). - Calculation exceeding
lockSeconds: If your computation takes 20 seconds butlockSecondsis set to 10 seconds, the lock will expire prematurely while the first worker is still running, allowing waiting workers to enter and recompute. Always setlockSecondshigher than your maximum expected computation time. waitSecondstoo short: If computation takes 4 seconds butwaitSecondsis set to 1 second, waiting requests will time out waiting for the lock and fall back to executing the query themselves.
1.3 Stale-While-Revalidate (flexible)
How it works:
When high-traffic cache entries expire, requests must synchronously wait for database computation. AtomicCache::flexible() implements the Stale-While-Revalidate (SWR) pattern:
- Fresh window: Returns cached data in
< 1ms. - Grace window (Stale): Returns existing cached data instantly (0ms latency spike to users) while deferring background revalidation until after the HTTP response has been flushed to the client (via Laravel 11's
defer()orapp()->terminating()). - Expired: If past total lifetime or on initial cache miss, computes synchronously via distributed atomic locking.
- OCC Protected: If models are updated and tags change while background revalidation is running, the stale write is safely discarded.
- Failure Backoff & Expiration Ceiling: If the revalidation callback throws an exception (e.g. database down), the error is reported and the stale TTL is extended by 30 seconds (bounded by remaining original expiration ceiling
__swr_expires_at__), preventing broken services from serving zombie data indefinitely.
use KaziOmar\AtomicCache\Facades\AtomicCache; // 1. Auto-grace: 3600s fresh TTL, grace period is automatically computed (+20%): $feed = AtomicCache::flexible('homepage_feed', 3600, function () { return HeavyFeedService::getFeed(); }); // 2. Laravel 11 Cache::flexible convention: [fresh_seconds, total_seconds] // Fresh for 300s (5m), total lifetime 1800s (30m, meaning 25m grace window): $stats = AtomicCache::flexible('global_stats', [300, 1800], function () { return HeavyReportingService::calculate(); }); // 3. Tagged SWR caching: $products = AtomicCache::tags(['products']) ->flexible('featured', [600, 3600], fn() => Product::featured());
Note
SWR SAPI & Deferred Execution:
Non-blocking background revalidation requires a web server environment that supports post-response flushing, such as PHP-FPM (with FastCGI response flushing) or Laravel Octane (FrankenPHP, RoadRunner, Swoole). In single-threaded blocking environments (such as local php artisan serve or CLI / queue commands), revalidation executes synchronously before returning.
1.4 Virtual Tagging Engine (Native & Non-Taggable Stores)
How it works:
In standard Laravel, calling Cache::tags(['products']) on file or database cache drivers crashes with a fatal exception: This cache store does not support tagging.
Atomic Cache introduces a Virtual Tag Versioning Engine:
- On Redis / Memcached / Array: Uses native driver tags for high-speed tagging.
- On File / Database / SQLite: Embeds atomic UUID version tokens into cache keys (
{prefix}:{key}:vt:{hash}). - When
AtomicCache::clearTags(['products'])is called, it replaces the virtual tag UUID in 0ms. All cached entries under that tag instantly experience a cache miss without requiring slow file directory traversals or heavy SQL deletes.
// Tagging reads and writes (works identically on Redis, File, Database, or Array): $catalog = AtomicCache::tags(['products', 'categories']) ->remember('catalog_active', 3600, fn() => Product::active()->get()); // Flushing all items under one or more tags: AtomicCache::clearTags(['products']); // Alias matching Laravel nomenclature: AtomicCache::flushTags(['products', 'categories']);
What will break it / What causes it not to work properly:
- Calling Laravel's native
Cache::tags()on non-taggable stores: Remember to always callAtomicCache::tags(). Calling Laravel's built-inCache::tags()directly will still crash onfileordatabasedrivers. - File driver disk accumulation: On the
filedriver, virtual tags invalidate entries logically in 0ms (subsequent reads miss immediately). However, the old serialized files remain on disk until their TTL expires or untilphp artisan cache:clearis run.
1.5 Manual Cache Invalidation Methods
How it works:
When performing operations that do not trigger automated model events (such as bulk updates or direct SQL queries), use these manual invalidation methods:
use KaziOmar\AtomicCache\Facades\AtomicCache; // 1. Invalidate an entire collection / resource (flushes tag "products"): AtomicCache::clearCollection('products'); AtomicCache::flushCollection('products'); // 2. Invalidate a single resource record (flushes tag "products:42"): AtomicCache::clearItem('products', 42); AtomicCache::forgetItem('products', 42); // 3. Invalidate specific tags: AtomicCache::clearTags(['products', 'stores:5']); AtomicCache::flushTags(['homepage_featured']); // 4. Invalidate an explicit key: AtomicCache::forget('my_custom_cache_key');
What will break it / What causes it not to work properly:
- Calling
AtomicCache::flush()on a shared cache store: CallingAtomicCache::flush()without active tags executesflush()on the underlying raw cache store. If your Redis store is shared with session or queue data, this will wipe user sessions! Always useclearTags()orclearCollection()instead offlush().
1.5 Automatic Payload Compression (Gzip)
How it works:
Large Eloquent collections or API responses consume megabytes of Redis/Memcached RAM. Whenever a cached payload exceeds 50 KB (configurable), Atomic Cache automatically compresses it with gzcompress:
- Reduces Redis/Memcached memory footprint by up to 70% to 80% (actual savings depend on payload structure and entropy).
- Decompression is completely transparent upon retrieval.
- Payloads smaller than 50 KB are stored raw without compression CPU overhead.
What will break it / What causes it not to work properly:
- Missing
ext-zlibextension: If PHP is compiled without thezlibextension, compression is automatically skipped and data is saved uncompressed without crashing your application. - High-entropy binary data: Payloads that are already compressed (such as JPEG images, PDF files, or zip archives) cannot be compressed further; Gzip will provide negligible reduction for them.
1.6 Transparent Chunking (Mega Datasets & Collections)
How it works:
Storing 10,000+ items or multi-megabyte collections in a single cache entry freezes Redis single-threaded loops and violates Memcached's strict 1MB key limit.
Atomic Cache includes Transparent Chunking:
- Arrays and Collections exceeding 1,000 items (or 800 KB estimated payload) are automatically partitioned across driver-safe chunk keys (
{key}:__chunk__:{generation}:{i}). - Generation UUIDs (Zero Torn Reads): All chunks are published under a unique generation UUID before the manifest pointer updates atomically, preventing concurrent readers from reading partial/torn data.
- Dynamic 800 KB Guard: Dynamically calculates items per chunk so individual chunk payloads never exceed 800 KB, remaining Memcached-safe.
- Key preservation: Associative string keys and sparse numeric array indexes are preserved upon reassembly.
- Collection restoration: Instances of
Illuminate\Support\Collectionare seamlessly reconstituted.
// Storing 20,000 items automatically splits into 20 safe chunks behind the scenes: $data = AtomicCache::remember('large_export', 3600, fn() => ExportRecord::all());
What will break it / What causes it not to work properly:
- Disabling chunking with Memcached: If you set
ATOMIC_CACHE_CHUNKING_ENABLED=falsein.envand attempt to cache a collection larger than 1MB on Memcached, Memcached will throw a payload size exception. - External key manipulation: Manually deleting an individual
{key}:__chunk__:...key in Redis will corrupt the chunk set. Atomic Cache's self-healing layer will detect the missing chunk, log a warning, and recompute the original data safely.
1.7 Cache TTL Jitter (Thundering Herd Variance)
How it works:
If you cache 1,000 database items simultaneously with a fixed TTL of 3,600 seconds, all 1,000 keys expire at the exact same microsecond, causing an instant CPU spike (known as the Thundering Herd problem).
withJitter() adds a small random variance (e.g. ±5%) to the TTL:
// TTL of 3600s will randomly vary between 3420s and 3780s: AtomicCache::withJitter(0.05)->remember('popular_feed', 3600, fn() => ...);
What will break it / What causes it not to work properly:
- Passing jitter percentages greater than 50%: The engine clamps jitter between 0% and 50% to prevent non-positive TTL calculations from deleting keys.
1.8 User-Scoped Caching (rememberForUser)
How it works:
Scopes the cache key to the currently authenticated user ID (atomic:user:{id}:{key}) or an explicit user ID:
// Automatically scopes to auth()->id(): $userMenu = AtomicCache::rememberForUser('user_menu', 3600, fn() => ...); // Explicit user ID scoping: $dashboard = AtomicCache::rememberForUser('dashboard', 3600, fn() => ..., userId: 42);
What will break it / What causes it not to work properly:
- Unauthenticated guest users sharing session-less state: If
rememberForUser()is called when no user is logged in (auth()->id() === null), Atomic Cache falls back to the current session ID (guest:{session_id}). If sessions are disabled or uninitialized, it falls back to a globalguestkey. Do not userememberForUserfor guest-facing public content.
1.9 Write Deduplication (Cache DNA)
How it works:
When ATOMIC_CACHE_DEDUPLICATION_ENABLED=true is enabled in .env, Atomic Cache hashes the serialized payload (Cache DNA) before writing. If identical content is already cached with a valid remaining TTL, it skips CPU-intensive Gzip re-compression and chunk re-splitting, refreshing the existing TTL in storage.
What will break it / What causes it not to work properly:
- Non-deterministic payloads: If your cached array includes dynamic timestamps like
now()or random tokens, every payload hash will differ, bypassing deduplication benefits.
1.10 Optimistic Concurrency Control (OCC)
How it works:
If a heavy calculation takes 4 seconds, and during second 2 an admin updates the database (flushing the tag), writing the 4-second-old result to the cache at second 4 would overwrite the update with stale data.
Atomic Cache dramatically minimizes stale cache writes using Optimistic Concurrency Control (OCC). It captures universal UUID version tokens per tag before computing the value. If a tag is cleared while a closure is executing, the token mismatch triggers an OCC discard, safely dropping the stale write instead of repopulating the cache with outdated data.
On virtual tag drivers (File, Database), TOCTOU race conditions are closed completely by baking the pre-computation version hash into the storage key. On native taggable stores (Redis, Memcached), the stale write window is minimized to microsecond intervals.
What will break it / What causes it not to work properly:
- Direct
Cache::tags([...])->flush()bypass: OCC relies onAtomicCache::clearTags(),flushTags(), or model events rotating the tag version token. If application code or a third-party package bypasses Atomic Cache and calls Laravel's nativeCache::tags([...])->flush()directly, the native tags are flushed but Atomic Cache's version tokens are not rotated. - External non-PHP invalidation: If an external service or raw Redis CLI command flushes Redis tags directly bypassing PHP, Atomic Cache cannot detect the external modification.
- Redis
allkeys-lrueviction: OCC version tokens are stored withforever(). If Redis runs out of memory under anallkeys-lrupolicy, Redis may evict version token keys. If evicted, the next access generates a fresh UUID token. This safely forces a cache miss (preventing stale data), but can temporarily elevate cache miss rates until repopulated. - Write-heavy tables with broad tags: On tables with continuous concurrent updates (e.g., streaming telemetry), OCC will repeatedly discard stale writes. For high-frequency write tables, cache targeted single-item keys instead of broad table collections.
1.11 Self-Healing Engine
How it works:
If a cached payload is corrupted, truncated by memory limits, or missing a chunk, Atomic Cache catches the deserialization exception, logs the event, purges the broken key, and silently recomputes fresh data from the callback without crashing the user's HTTP request.
1.12 Transaction Guard (Active Database Transaction Bypass)
How it works:
Running cache remember() inside an uncommitted database transaction (DB::transaction(...)) poses a serious dirty-read and phantom-cache risk: if the transaction rolls back, uncommitted data written to cache becomes a ghost entry that misleads users for hours.
When bypass_during_transactions is enabled (default: true), Atomic Cache detects active transactions across all opened database connections (DB::transactionLevel() > 0). In this state, remember() bypasses reading and writing to cache entirely, executing the closure directly and returning fresh database data. If the transaction rolls back, no phantom cache remains.
DB::transaction(function () { $order = Order::create([...]); // Bypasses cache: returns fresh $order without writing to cache store $latest = AtomicCache::remember('latest_order', 3600, fn() => Order::latest()->first()); if ($someError) { throw new \Exception("Rollback!"); // No phantom cache remains in Redis! } });
To explicitly disable this bypass for a specific operation or testing:
AtomicCache::withoutTransactionBypass()->remember('key', 3600, fn() => ...);
Warning
Important Testing Warning (RefreshDatabase & DatabaseTransactions):
If your feature tests use Laravel's RefreshDatabase or DatabaseTransactions traits, the entire test runs inside an uncommitted database transaction (transactionLevel() === 1).
Because bypass_during_transactions is enabled by default, cache remember() calls will always bypass cache during those tests!
To test cache hits inside transactional feature tests, disable the bypass in your phpunit.xml:
<env name="ATOMIC_CACHE_BYPASS_DURING_TRANSACTIONS" value="false"/>
or use AtomicCache::withoutTransactionBypass()->remember(...).
Transaction Middleware Alert: If your application uses HTTP middleware that wraps every request in a database transaction (DB::beginTransaction() ... DB::commit()), cache remember() will be bypassed by default unless ATOMIC_CACHE_BYPASS_DURING_TRANSACTIONS=false is configured.
Multi-Connection Detection: The guard checks all open connections (DB::getConnections()). If any open database connection has an active transaction, cache operations are bypassed.
Layer 2: Eloquent Model Lifecycle (AutoClearsCache)
Add AutoClearsCache to any Eloquent model to automate invalidations.
2.1 Automatic Invalidation on DB::afterCommit
How it works:
Hooks into Eloquent model events: created, updated, deleted, and restored (for SoftDeletes).
When a record changes:
- Resolves item tag:
{table}:{id}(e.g.products:42). - Resolves collection tag:
{table}(e.g.products). - Resolves parent relation tags (if
$cacheParentsis declared). - Resolves custom related tags (if
$relatedCacheTagsis declared). - Defers clearing until
$connection->afterCommit(). If a database transaction rolls back, your cache remains completely untouched!
namespace App\Models; use Illuminate\Database\Eloquent\Model; use KaziOmar\AtomicCache\Traits\AutoClearsCache; class Product extends Model { use AutoClearsCache; // Optional: Invalidate additional related tags when any product changes: protected array $relatedCacheTags = ['landing_page_stats']; }
2.2 Declarative Parent Invalidation ($cacheParents)
How it works:
Similar in spirit to Laravel's native $touches (operating on a single-level BelongsTo relation), you can declare parent relationships to automatically invalidate parent-scoped cache tags whenever a child record changes:
namespace App\Models; use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\Relations\BelongsTo; use KaziOmar\AtomicCache\Traits\AutoClearsCache; class Order extends Model { use AutoClearsCache; // Automatically invalidates Store caches when an Order changes: protected array $cacheParents = ['store']; public function store(): BelongsTo { return $this->belongsTo(Store::class); } }
When an order for Store #5 is created or updated:
- Flushes child item tag:
orders:{id} - Flushes child collection tag:
orders - Flushes parent scoped tag:
stores:5:orders - Flushes parent umbrella tag:
stores:5 - Dirty Foreign Key Handling: If an order is moved from Store 1 to Store 2 (
$order->store_id = 2), Atomic Cache invalidates tags for both Store 1 and Store 2!
Note
Parent Umbrella Tag Scope: By design, $cacheParents flushes both the scoped collection tag (stores:5:orders) and the parent umbrella tag (stores:5). If your application caches the parent model's own record under stores:5, child writes will also refresh the parent's general cache.
2.3 Model-Level Manual Cache Flushing (flushCache & clearCache)
AutoClearsCache provides two convenient helper methods directly on the model:
// 1. Instance helper: manually clear this record and its parent tags: $product = Product::find(42); $product->clearCache(); // Expressive alias for clearModelCacheOnCommit() // 2. Static helper: flush all collection-level caches for this model's table: Product::where('category_id', 5)->update(['discount' => 10]); Product::flushCache(); // Wipes all "products" table collection caches in one line!
Important
Important Scope Note: Product::flushCache() invalidates the model's table collection tag (products). It does not invalidate individual item tags (products:42) or parent-scoped relation tags (stores:5:orders). If your model uses parent-scoped caching ($cacheParents), invalidate those tags explicitly via AtomicCache::clearTags(['stores:5:orders', 'stores:5']).
Transaction Safety: Unlike model lifecycle events which wait for afterCommit, Product::flushCache() executes immediately. If calling it inside an active DB::transaction(), wrap it in DB::afterCommit(fn() => Product::flushCache()) to prevent concurrent readers from caching pre-committed data.
2.4 High-Frequency Update Columns ($cacheIgnoreColumns)
When updating counters or analytics (e.g. view_count, last_login_at, login_count), invalidating the entire table collection cache (products) or parent cache (stores:1:products) on every single page view causes severe cache churn.
Declare $cacheIgnoreColumns on your model to protect collections:
class Product extends Model { use AutoClearsCache; protected array $cacheParents = ['store']; // Only single-item cache ('products:42') is cleared when these change. // Heavy table collections ('products') and parent tags ('stores:1:products') remain cached: protected array $cacheIgnoreColumns = ['view_count', 'meta']; }
Note
Automatic Timestamp Exclusion: Laravel automatically dirties the updated_at column on save. Atomic Cache automatically ignores updated_at when evaluating $cacheIgnoreColumns. If you call $model->touch(), Atomic Cache verifies that no declared ignored column changed and correctly flushes the collection cache.
Create & Delete Safety: $cacheIgnoreColumns only applies to updated events. Model created, deleted, and restored events always invalidate collection tags regardless of this setting.
[!WARNING]
Stale Display & Sorting Warning:
Columns added to $cacheIgnoreColumns will remain stale in cached query results and listings until their TTL expires.
For example, if you ignore view_count, any cached query that selects, filters (where), or orders by (orderBy('view_count')) will display the old view count or stale ordering until refreshed.
Rule of Thumb: Only ignore columns that are not displayed in cached queries or critical sorting operations (e.g. internal telemetry, session metadata, or live counters rendered via dedicated un-cached endpoints).
2.5 Strict Mode for Parent Relations (strict_mode)
Catch typos and invalid relationship declarations early during local development:
// config/atomic-cache.php 'strict_mode' => env('ATOMIC_CACHE_STRICT_MODE', null), // null = active in local (app()->isLocal()) // null = active in local environment (app()->isLocal() === true)
When strict mode is enabled (default in local development, or by setting ATOMIC_CACHE_STRICT_MODE=true in phpunit.xml), invalid declarations throw an immediate \InvalidArgumentException with clear guidance:
- Typo in method name (
$cacheParents = ['strore']): throws missing method error. - Class name passed instead of relation method (
$cacheParents = [Store::class]): detects class name and asks: "Did you pass a class name instead of the BelongsTo relation method name?". - Invalid type passed (
$cacheParents = [123]): throws invalid type error. - Method requiring parameters (
public function store($type)): throws required parameter error. - Non-
BelongsTorelations (hasMany,morphTo): throws relation type error.
In production environments, strict mode safely logs a warning and gracefully continues without interrupting customer transactions.
2.6 Transaction-Safe Bulk Invalidation (AtomicCache::invalidating)
For bulk updates, mass deletes, or service workflows using direct DB queries, wrap execution with AtomicCache::invalidating():
use KaziOmar\AtomicCache\Facades\AtomicCache; // Outside transaction: flushes immediately // Inside transaction: automatically defers invalidation to DB::afterCommit! AtomicCache::invalidating([Order::class, Product::class], function () { DB::table('orders')->where('status', 'draft')->delete(); DB::table('products')->where('stock', 0)->update(['status' => 'out_of_stock']); });
Uses a try/finally guarantee: outside a transaction, invalidation is guaranteed in a finally block even if the closure throws an exception, preventing stale reads after partial database mutations. Inside an active database transaction, invalidation is safely registered via DB::afterCommit(). If the transaction rolls back, cache is untouched.
2.7 Critical Rules & What Breaks Model Auto-Invalidation
- Mass queries bypass model events: Direct query builder mutations (
Product::where(...)->update(...),delete(), orDB::table('products')->update(...)) do not fire Eloquent events. AutoClearsCache cannot detect them.- Solution: Run
Product::flushCache();right after your bulk query.
- Solution: Run
- Quiet operations bypass events: Calling
$model->saveQuietly(),updateQuietly(),deleteQuietly(), or wrapping code inModel::withoutEvents()intentionally suppresses model events.- Solution: Manually call
$model->clearCache()if you need invalidation after quiet saves.
- Solution: Manually call
- Pivot table changes: Many-to-many
attach(),detach(), orsync()operations on relationships do not fire parent model events.- Solution: Call
AtomicCache::clearTags([Product::class, Category::class])explicitly after syncing.
- Solution: Call
$cacheParentsonly supportsBelongsTo: DeclaringhasMany,hasOne,belongsToMany, ormorphToin$cacheParentswill throw anInvalidArgumentExceptionin strict mode (local/testing) or log a warning in production.- Custom owner keys are skipped: If a relationship uses a custom non-primary owner key (e.g.
belongsTo(Store::class, 'store_slug', 'slug')), it is skipped because the child model holds a string slug rather than the parent's primary ID, which would create mismatched umbrella tags (stores:nikevsstores:5). - Grandparent relations do not auto-cascade (
$touchesdoes not work): Multi-level hierarchies (e.g.OrderItem -> Order -> Store) do not automatically cascade from item to store. Crucially, Laravel's nativeprotected $touches = ['order']property executes a raw database update (rawUpdate) and does NOT fire Eloquent model events. Thus, declaring$toucheswill not triggerAutoClearsCacheon the parent!- Solution 1 (Recommended - Explicit Method): Define
getRelatedCacheTags()on the child model:public function getRelatedCacheTags(): array { return [ "stores:{$this->order->store_id}:orders", "stores:{$this->order->store_id}", ]; }
- Solution 2 (Manual Touch): Call
$orderItem->order->touch()directly on the model instance (which callssave()and fires Eloquent'supdatedevent).
- Solution 1 (Recommended - Explicit Method): Define
- Runtime property mutation is ignored: Because configured parent relations are cached in-memory per class for performance, dynamically modifying
$model->cacheParents = [...]on an active model instance at runtime will have no effect. - Octane / Long-Running Workers: If you dynamically manipulate
$cacheParentsduring testing or worker loops, clear the in-memory cache viaModel::flushConfiguredParentRelationsCache(). - Rolled-back transactions do not clear cache: If changes occur inside a
DB::transaction()that throws an exception and rolls back,afterCommit()will not fire. The cache remains untouched.
Layer 3: Query Builder Macros (->atomicCache())
3.1 Zero-Key Query & First Record Caching
How it works:
Chain ->atomicCache() directly off any Eloquent or Query Builder query:
use App\Models\Product; use Illuminate\Support\Facades\DB; // 1. Auto-generates sha256 hash from SQL + bindings + eager loads // Automatically tagged with 'products' and Product::class for auto-invalidation: $featured = Product::where('status', 'active')->where('featured', 1)->atomicCache(3600); // 2. Single record caching: $product = Product::where('slug', $slug)->atomicCacheFirst(3600); // 3. Custom key mode: $bestSellers = Product::where('sales', '>', 500)->atomicCache('bestsellers', 7200); // 4. Scoped Tagging & Tenant Isolation (Omits broad 'orders' table tag): // Omits the broad 'orders' table tag and tags strictly with the scoped tag: $storeOrders = Order::where('store_id', 5)->atomicCache(scope: 'stores:5:orders'); $storeFirst = Order::where('store_id', 5)->latest()->atomicCacheFirst(scope: 'stores:5:orders'); // 5. Works on DB facade and relationships: $stats = DB::table('orders')->where('status', 'paid')->atomicCache(1800); $userOrders = $user->orders()->latest()->atomicCache(3600);
3.2 Paginated Queries & Aggregations
Atomic Cache provides dedicated query macros for caching paginated result sets and database aggregations:
use App\Models\Post; use App\Models\User; use App\Models\Order; // 1. Full Pagination (caches LengthAwarePaginator with page & query fingerprint): $paginatedPosts = Post::where('status', 'published') ->latest() ->atomicCachePaginate(15, 3600); // With custom parameters: $paginated = Post::atomicCachePaginate(perPage: 20, ttl: 1800); // 2. Simple Pagination (caches SimplePaginator without total count query): $simplePosts = Post::where('status', 'published') ->atomicCacheSimplePaginate(15, 3600); // 3. Cached Count Aggregation (SQL COUNT without hydrating full models into memory): $totalActiveUsers = User::where('active', 1)->atomicCacheCount(300); // COUNT(*) with 300s TTL $uniqueSkus = Product::atomicCacheCount('sku', 600); // COUNT('sku') with 600s TTL $customCount = Product::atomicCacheCount('*', 'active_prod_count', 600); // Custom key with 600s TTL // 4. Cached Exists Check (SQL EXISTS boolean): $hasPendingOrders = Order::where('status', 'pending')->atomicCacheExists(60);
Tip
atomicCacheCount Parameter Order:
Following Laravel's native query builder count($columns = '*'), the first argument to atomicCacheCount() specifies the SQL column name (defaults to '*'). If a numeric integer or DateTime TTL is passed as the first argument (e.g. atomicCacheCount(300)), the macro automatically recognizes it as the cache TTL and counts '*'. To provide a custom cache key along with columns, pass: atomicCacheCount('*', 'my_custom_key', 600).
3.3 Critical Rules & What Breaks Query Macros
- Chaining
->paginate()after->atomicCache():atomicCache()executes->get()immediately and returns an Eloquent/SupportCollection. Chaining->paginate()afterward will throw a fatal error:Method paginate does not exist on Collection.- Solution: Call
->atomicCachePaginate(15)directly on the builder!
- Mass updates will not clear query macro caches:
- If you cache a query via
Product::where('active', 1)->atomicCache(), runningProduct::where('active', 1)->update(['price' => 20])will not clear the cache because no Eloquent event fires. - Solution: Call
Product::flushCache();after the update.
- If you cache a query via
scope:queries and mass updates:Order::flushCache()orinvalidating([Order::class], ...)only invalidates the baseorderscollection tag. Scoped queries cached viascope: 'stores:5:orders'will not be cleared by broad table flushes.- Solution: Invalidate the scoped tag explicitly during mass updates:
AtomicCache::invalidating(['stores:5:orders', Order::class], fn() => ...);orAtomicCache::clearTags(['stores:5:orders']).
scope:queries omit automatic joins & require$cacheParents:- When
scope:is passed, automatic join-table tagging is omitted in favor of your explicit scope tag. Furthermore, model lifecycle events (Order::create()) will only invalidate the scoped cache if the model defines a matching$cacheParentsrelation (e.g.protected array $cacheParents = ['store'];).
- When
- Eager loading does not auto-tag related tables:
- Eager-loaded relationships (
Product::with('category')->atomicCache()) are included in the query hash fingerprint, but related tables (categories) are not auto-tagged. If a category is updated, the product query cache will not automatically invalidate. - Solution: Pass related table tags explicitly:
->atomicCache(3600, tags: ['categories']).
- Eager-loaded relationships (
- Raw SQL subqueries are not auto-tagged:
- While standard
join()andleftJoin()methods are inspected and auto-tagged, raw SQL joins or subqueries (whereRaw('exists (select 1 from categories ...)')) cannot be parsed for table names. - Solution: Pass additional table tags explicitly:
->atomicCache(3600, tags: ['categories']).
- While standard
- Parameter order vigilance:
- The signature is
atomicCache($keyOrTtl = null, $ttl = null, array $tags = []). Passing$query->atomicCache(3600)treats3600as TTL. If you want a custom key, pass the key first:$query->atomicCache('my_key', 3600).
- The signature is
Layer 4: Service & Repository Layer (HasAtomicCache)
Standardize caching in your service or repository classes by adding the HasAtomicCache trait.
4.1 Automatic Method-Level Caching ($this->cache())
How it works:
Instead of manually inventing and maintaining custom cache key strings across your codebase, you can cache any service method directly by passing PHP's native __FUNCTION__ and func_get_args():
namespace App\Services; use App\Models\Category; use KaziOmar\AtomicCache\Traits\HasAtomicCache; class CategoryService { use HasAtomicCache; // Optional: Defaults to 'categories' (derived from class name) protected string $cacheResource = 'categories'; /** * Cache list queries by method name and arguments. */ public function getAllCategories() { $callback = fn () => Category::withCount('products') ->where('is_active', true) ->get(); return $this->cache(__FUNCTION__, func_get_args(), $callback, ttl: 3600); } /** * Cache single records with dynamic arguments. */ public function getCategoryBySlug(string $slug): ?Category { $callback = fn () => Category::with(['subcategories' => fn ($q) => $q->active()]) ->where('slug', $slug) ->firstOrFail(); return $this->cache(__FUNCTION__, func_get_args(), $callback, ttl: 3600); } /** * Cache complex multi-parameter analytical or aggregation queries. */ public function getCategoryMetrics(int $categoryId, string $metricType = 'daily') { return $this->cache(__FUNCTION__, func_get_args(), function () use ($categoryId, $metricType) { // Expensive aggregation or external service calls... return [ 'category_id' => $categoryId, 'metric' => $metricType, 'calculated_at' => now()->toDateTimeString(), ]; }, ttl: 1800); } }
What do __FUNCTION__ and func_get_args() do?
__FUNCTION__: A native PHP magic constant that automatically returns the string name of the current enclosing function or method (e.g.'getAllCategories'or'getCategoryBySlug').func_get_args(): A native PHP function that returns an indexed array of all runtime arguments passed into the method (e.g.[]forgetAllCategories(), or['electronics']forgetCategoryBySlug('electronics')).- Deterministic Key Composition: Atomic Cache combines the resource tag, method name, and a serialized MD5 hash of safe arguments to form a collision-proof cache key:
- Without arguments:
{resource}:{method}→categories:getAllCategories - With arguments:
{resource}:{method}:{argsHash}→categories:getCategoryBySlug:9df2a4...
- Without arguments:
- Safe Argument Normalization: If your method receives Eloquent models, closures, or complex objects, Atomic Cache normalizes them into lightweight identifiers (
App\Models\Category:12) so PHP'sserialize()never throws un-serializable errors.
Method Signature & Additional Options:
public function cache( string $method, array $args = [], ?Closure $callback = null, ?int $ttl = null, bool|array|null $perUserOrTags = null, bool $lock = false ): mixed
ttl: Cache lifetime in seconds (defaults to class$cacheTTLproperty or3600).perUserOrTags:- Pass
trueto isolate the cache per authenticated user (guestfor unauthenticated sessions). - Pass an array of tags (e.g.
perUserOrTags: ['categories', 'products']) if the query depends on multiple database tables so changes in either table will invalidate this cache.
- Pass
lock: true: Activates atomic distributed locking to prevent stampede herd conditions during cache warmup.
4.2 Pagination & Filter Isolation (rememberCollection)
How it works:
When caching paginated or filtered lists, rememberCollection() automatically inspects request()->query() and hashes the page number and filters into the cache key:
namespace App\Services; use App\Models\Product; use KaziOmar\AtomicCache\Traits\HasAtomicCache; class ProductService { use HasAtomicCache; protected string $cacheResource = 'products'; // Resource name and cache tag public function getActiveProducts() { // GET /products?page=1 and GET /products?page=2 are cached separately: return $this->rememberCollection('active', fn() => Product::where('status', 'active')->paginate(15)); } }
4.3 Single Item Caching (rememberItem / cacheItem)
public function findProduct(int $id) { // Caches under key "products:{id}", tagged with "products:{id}" and "products": return $this->rememberItem($id, fn() => Product::findOrFail($id)); }
4.4 Service-Level Cache Invalidation Helpers
When performing write operations (create, update, delete) inside your service, you can invalidate the relevant cached scopes directly from within the service:
public function updateCategory(int $id, array $data): Category { $category = Category::findOrFail($id); $category->update($data); // 1. Invalidate a single item key ("categories:{id}"): $this->clearItemCache($id); // 2. Invalidate all collection/list queries for this resource: $this->clearCollectionCache(); // 3. Or wipe all caches (items + collections) under this resource tag: $this->clearAllCache(); return $category; }
4.5 Query Parameter Sanitization & Whitelisting
To prevent Cache Fragmentation, rememberCollection automatically strips common marketing and tracking query parameters (utm_*, fbclid, gclid, ttclid, ref, etc.). When 10,000 visitors arrive from ad campaigns with unique tracking IDs, they all share the exact same cached payload!
To enforce an explicit whitelist of allowed query parameters:
class ProductService { use HasAtomicCache; // Only these parameters will be hashed into the cache key: protected array $allowedQueryParams = ['page', 'sort', 'category']; }
4.6 DoS & Cache Poisoning Limits
To protect against memory exhaustion attacks, Atomic Cache enforces strict limits on request queries:
- Max Parameters (Default: 20): Queries exceeding 20 parameters cleanly bypass the cache and run against the database.
- Max Size (Default: 2048 bytes): Serialized query strings exceeding 2KB cleanly bypass caching.
4.7 Service Configuration Reference
Configure caching behavior per service by declaring optional protected properties:
class ProductService { use HasAtomicCache; // Custom base tag & key prefix (defaults to snake_plural of class name without Service/Repository): protected string $cacheResource = 'products'; // Default TTL in seconds for all cache calls in this class (defaults to 3600): protected int $cacheTTL = 7200; // Automatically scope all caches in this class per authenticated user (defaults to false): protected bool $cachePerUser = false; // Whitelist allowed query parameters for request pagination & filters (DDoS prevention): protected array $allowedQueryParams = ['page', 'sort', 'filter']; // Master kill-switch to bypass caching during tests or debugging (defaults to true): protected bool $cachingEnabled = true; }
4.8 Critical Rules & What Breaks Service Caching
- Do NOT use
remember()for paginated data:- If you call
$this->remember('active_products', 3600, fn() => Product::paginate(15))instead ofrememberCollection(), it will not inspectrequest()->query(). Page 1 results will be cached and returned for Page 2, Page 3, and all other pages! Always userememberCollection().
- If you call
- Resource name guessing mismatches:
- If your service class is named
CatalogManager, the trait guesses the resource tag as'catalog_managers'. If your database table isproducts,Productmodel events will clear'products', leaving'catalog_managers'stale! - Solution: Always explicitly declare
protected string $cacheResource = 'products';when the class name does not match the table name.
- If your service class is named
- Un-serializable objects in
$extraArgs:- Passing closures with un-serializable references into
$extraArgswill prevent deterministic cache key generation. Pass scalar values (integers, strings, arrays) instead.
- Passing closures with un-serializable references into
Layer 5: Blade Fragment Caching (@atomicCache)
5.1 Usage & Tagging
Cache expensive HTML blocks, navigation bars, and widgets directly in your Blade views:
{{-- Caches rendered HTML for 3600 seconds, tagged with 'categories' and 'sub_categories' --}} @atomicCache('sidebar_categories', 3600, ['categories', 'sub_categories']) <div class="sidebar"> @foreach(\App\Models\Category::with('subcategories')->get() as $category) <h3>{{ $category->name }}</h3> @foreach($category->subcategories as $sub) <p>{{ $sub->title }}</p> @endforeach @endforeach </div> @endAtomicCache
5.2 Critical Rules & What Breaks Blade Caching
- Multi-table dependencies: If your cached Blade fragment renders data from multiple models/tables (such as categories and subcategories), specify all relevant tags:
@atomicCache('sidebar', 3600, ['categories', 'sub_categories']). If you only pass'categories', updates to subcategories will not invalidate the cached HTML. - Never cache
@csrfor forms inside a fragment:- CSRF tokens are unique to each user session. If you cache a form containing
@csrf, the first user's CSRF token is stored. When subsequent users submit the form, they will receive a419 Page Expirederror!
- CSRF tokens are unique to each user session. If you cache a form containing
- Never cache user-specific data without user scoping:
- If you cache a block containing
@atomicCache('user_header')with the user's name or cart count, User A's personal information will be cached and shown to User B (a major data leak). - Solution: Append the user ID to the key:
@atomicCache('user_header_' . auth()->id(), 3600).
- If you cache a block containing
- Never cache session flash messages or
@errordirectives:session('status')or@error('email')cached inside a fragment will either never display or remain permanently visible to all subsequent visitors.
- Unclosed
@atomicCacheblocks:- Omitting
@endAtomicCacheleaves an active PHP output buffer open, which can break page rendering.
- Omitting
Layer 6: CLI Diagnostics & Auditing
6.1 Model Architecture Auditor (atomic-cache:check)
Scan your entire application's Eloquent models to verify cache invalidation tags and inspect architectural health:
php artisan atomic-cache:check php artisan atomic-cache:check --path=app/Domain/Shop/Models php artisan atomic-cache:check --filter=recommended php artisan atomic-cache:check --json
6.2 Performance Benchmark CLI (atomic-cache:bench)
Benchmark your cache latency, Gzip payload reduction, and chunking integrity in real-time:
php artisan atomic-cache:bench php artisan atomic-cache:bench --driver=redis --iterations=10
6.3 Safe Cache Clearing CLI (atomic-cache:clear)
# Clear a specific tag or key: php artisan atomic-cache:clear products # Clear multiple tags simultaneously: php artisan atomic-cache:clear --tags=products,categories # Clear entire cache store (requires confirmation in production): php artisan atomic-cache:clear --all # Clear entire store non-interactively (e.g. CI / deployments): php artisan atomic-cache:clear --all --force
Warning
Running --all flushes the entire cache store via flush(). If your cache store is shared with Redis sessions or queue workers, use --tags= or configure a dedicated cache store to avoid purging session data.
Driver Compatibility Matrix
Atomic Cache dynamically evaluates your cache store: taggable stores utilize native tags, while non-taggable stores automatically receive virtual tagging.
| Driver | Tag Support | Stampede Locks | CI Matrix Status | Notes |
|---|---|---|---|---|
redis |
Native | Yes | Tested in CI | Recommended for high-concurrency production. In production with high writes, schedule Laravel's php artisan cache:prune-stale-tags. |
file |
Virtual | Yes | Tested in CI | Default local dev store. Virtual tags provide zero-crash tagging. FileStore supports locks natively. |
database |
Virtual | Yes | Compatible | Works on MySQL, PostgreSQL, SQLite, and SQL Server without extra setup. |
array |
Native | Yes | Tested in CI | In-memory per process (ArrayStore is taggable). Ideal for PHPUnit and automated test suites. |
memcached |
Native | Yes | Compatible | 1 MB item limit: the transparent 800 KB chunk guard and Gzip compression protect against key overflow. |
dynamodb |
Virtual | Yes | Compatible | Items limited to 400 KB; configure ATOMIC_CACHE_CHUNK_MAX_BYTES below 400,000. |
Configuration Reference
Publish config/atomic-cache.php to customize package behavior:
return [ 'enabled' => env('ATOMIC_CACHE_ENABLED', true), 'bypass_during_transactions' => env('ATOMIC_CACHE_BYPASS_DURING_TRANSACTIONS', true), 'strict_mode' => env('ATOMIC_CACHE_STRICT_MODE', null), // null = active in local (app()->isLocal()) 'default_ttl' => env('ATOMIC_CACHE_DEFAULT_TTL', 3600), 'store' => env('ATOMIC_CACHE_STORE', null), 'prefix' => env('ATOMIC_CACHE_PREFIX', 'atomic'), 'stampede' => [ 'enabled' => env('ATOMIC_CACHE_STAMPEDE_ENABLED', true), 'lock_seconds' => env('ATOMIC_CACHE_LOCK_SECONDS', 10), 'wait_seconds' => env('ATOMIC_CACHE_WAIT_SECONDS', 5), ], 'compression' => [ 'enabled' => env('ATOMIC_CACHE_COMPRESSION_ENABLED', true), 'threshold' => env('ATOMIC_CACHE_COMPRESSION_THRESHOLD', 51200), // 50 KB 'level' => env('ATOMIC_CACHE_COMPRESSION_LEVEL', 6), ], 'chunking' => [ 'enabled' => env('ATOMIC_CACHE_CHUNKING_ENABLED', true), 'threshold' => env('ATOMIC_CACHE_CHUNKING_THRESHOLD', 1000), 'chunk_size' => env('ATOMIC_CACHE_CHUNK_SIZE', 1000), 'max_bytes' => env('ATOMIC_CACHE_CHUNK_MAX_BYTES', 800000), // 800 KB ceiling 'clean_on_put' => env('ATOMIC_CACHE_CHUNKING_CLEAN_ON_PUT', false), ], 'deduplication' => [ 'enabled' => env('ATOMIC_CACHE_DEDUPLICATION_ENABLED', false), ], 'self_healing' => [ 'enabled' => env('ATOMIC_CACHE_SELF_HEALING', true), 'log_corrupted' => env('ATOMIC_CACHE_LOG_CORRUPTED', true), ], 'jitter' => [ 'enabled' => env('ATOMIC_CACHE_JITTER_ENABLED', false), 'percentage' => env('ATOMIC_CACHE_JITTER_PERCENTAGE', 5), // ±5% ], 'ignored_query_parameters' => [ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'wbraid', 'gbraid', 'ttclid', 'msclkid', 'mc_cid', 'mc_eid', '_ga', '_gl', '_gid', 'ref', ], 'query_limits' => [ 'max_params' => env('ATOMIC_CACHE_QUERY_MAX_PARAMS', 20), 'max_bytes' => env('ATOMIC_CACHE_QUERY_MAX_BYTES', 2048), ], ];
Environment Variables (.env) Reference
| Variable | Default | Description |
|---|---|---|
ATOMIC_CACHE_ENABLED |
true |
Master switch to enable or disable atomic caching globally |
ATOMIC_CACHE_DEFAULT_TTL |
3600 |
Default cache lifetime in seconds when none is specified |
ATOMIC_CACHE_STORE |
null |
Dedicated cache store (e.g. 'redis'); null uses config('cache.default') |
ATOMIC_CACHE_PREFIX |
atomic |
Key namespace prefix (in multi-tenant apps, set uniquely per tenant) |
ATOMIC_CACHE_STAMPEDE_ENABLED |
true |
Enable atomic distributed locking by default |
ATOMIC_CACHE_LOCK_SECONDS |
10 |
Maximum lock hold duration during closure calculation |
ATOMIC_CACHE_WAIT_SECONDS |
5 |
Maximum seconds concurrent requests will wait for computation |
ATOMIC_CACHE_BYPASS_DURING_TRANSACTIONS |
true |
Bypass cache reads/writes inside active DB transactions to prevent dirty reads |
ATOMIC_CACHE_STRICT_MODE |
null |
Strict parent relation validation (null enables in local development) |
ATOMIC_CACHE_COMPRESSION_ENABLED |
true |
Auto-compress payloads exceeding compression threshold |
ATOMIC_CACHE_COMPRESSION_THRESHOLD |
51200 |
Minimum serialized byte size to trigger Gzip compression (50 KB) |
ATOMIC_CACHE_COMPRESSION_LEVEL |
6 |
Gzip compression level (1-9) |
ATOMIC_CACHE_SELF_HEALING |
true |
Purges corrupt/truncated cache entries and recalculates on cache miss |
ATOMIC_CACHE_LOG_CORRUPTED |
true |
Logs warnings when a corrupted cache payload is detected and self-healed |
ATOMIC_CACHE_CHUNKING_ENABLED |
true |
Auto-partition large datasets into driver-safe chunk keys |
ATOMIC_CACHE_CHUNKING_THRESHOLD |
1000 |
Item count threshold required to trigger transparent chunking |
ATOMIC_CACHE_CHUNK_SIZE |
1000 |
Item count per partitioned chunk |
ATOMIC_CACHE_CHUNK_MAX_BYTES |
800000 |
Maximum byte ceiling per chunk payload (800 KB for Memcached 1MB limit) |
ATOMIC_CACHE_CHUNKING_CLEAN_ON_PUT |
false |
When true, non-chunked put purges prior chunk keys eagerly |
ATOMIC_CACHE_DEDUPLICATION_ENABLED |
false |
Opt-in DNA hashing: skips compression and chunk re-splitting if identical content is cached |
ATOMIC_CACHE_JITTER_ENABLED |
false |
Enable random TTL variance globally |
ATOMIC_CACHE_JITTER_PERCENTAGE |
5 |
Jitter variance percentage (±5%) |
ATOMIC_CACHE_QUERY_MAX_PARAMS |
20 |
Max allowed sanitized HTTP query parameters before bypassing cache |
ATOMIC_CACHE_QUERY_MAX_BYTES |
2048 |
Max allowed serialized query string size before bypassing cache |
Troubleshooting & FAQ
1. The cache is not cleared after updating data
| Possible Cause | Recommended Fix |
|---|---|
Mass Eloquent Mutations: Model::where()->update(), delete(), insert(), or DB::table(). These bypass Eloquent model events. |
Call Product::flushCache(); or AtomicCache::clearCollection('products') right after the bulk query. |
Missing Trait: Model does not use AutoClearsCache. |
Add use AutoClearsCache; to the model. Run php artisan atomic-cache:check to audit your models. |
Quiet Operations: Using saveQuietly(), updateQuietly(), or withoutEvents(). |
These suppress model events by design. Call $product->clearCache() manually. |
Pivot Table Changes: Many-to-many attach(), detach(), or sync(). |
Pivot mutations do not fire parent model events. Call AtomicCache::clearTags(...) on the related models after syncing. |
Rolled-back Transactions: The write ran inside a DB::transaction(...) that rolled back. |
AutoClearsCache uses DB::afterCommit. If the transaction rolls back, no database changes occurred, so cache remains intact. |
Custom Owner Keys: A child model uses a custom owner key (e.g. belongsTo(Store::class, 'slug', 'slug')). |
$cacheParents automatically skips custom owner keys to prevent mismatched umbrella tags. Invalidate parent tags manually. |
2. The cache never hits (always a miss)
| Possible Cause | Recommended Fix |
|---|---|
Caching Disabled: ATOMIC_CACHE_ENABLED=false in .env. |
Enable it in your environment: ATOMIC_CACHE_ENABLED=true. |
| Query Parameter Limits Exceeded: The request has more than 20 query parameters or query string exceeds 2048 bytes. | AtomicCache bypasses caching on abnormal queries to protect against Cache Poisoning DoS attacks. Adjust ATOMIC_CACHE_QUERY_MAX_PARAMS or ATOMIC_CACHE_QUERY_MAX_BYTES if legitimate requests are large. |
OCC Discard on High Writes: Tags were invalidated while the remember() closure was computing. |
Expected behavior under Optimistic Concurrency Control. On write-heavy tables, use targeted single-record keys instead of broad table tags. |
| Computed TTL <= 0: TTL is 0, negative, or in the past. | AtomicCache forgets/clears keys when given a non-positive TTL or past DateTimeInterface. Verify your TTL logic. |
3. Common Architecture Questions
"Tags are flushed but keys remain in Redis on Laravel 10"
On Laravel 10 combined with phpredis 6.1 or newer, native Laravel Redis tag clearing could fail to scan tag entries on flush(). Atomic Cache includes an automatic direct tag purge mechanism for this combination. In high-write production environments on Redis, also schedule Laravel's native tag pruning command:
// In routes/console.php or app/Console/Kernel.php: Schedule::command('cache:prune-stale-tags')->hourly();
"atomic-cache:clear --all cleared my sessions and queues"
Using --all flushes the entire configured cache store via flush(). If your cache store is shared with sessions or queue jobs, invalidate specific tags (e.g. php artisan atomic-cache:clear --tags=products). To isolate application caches from sessions, configure a dedicated cache store via ATOMIC_CACHE_STORE.
"Multi-Tenant applications sharing cache"
In multi-tenant setups, models with similar IDs across tenants (e.g. Tenant A Order #5 and Tenant B Order #5) will resolve identical tags (orders:5). To prevent cross-tenant collisions, configure a dynamic tenant-specific prefix in config('atomic-cache.prefix') during tenant identification.
Note on Native Redis Tags: When using Redis native tags (TaggedCache), Laravel's underlying tag set key (tag:orders:entries) is not prefixed by custom runtime prefixes unless the Redis cache store connection itself has a dedicated prefix. In single-Redis shared multi-tenant databases, invalidating AtomicCache::clearTags(['orders']) in Tenant A will also flush the native orders tag set in Tenant B (causing over-invalidation, though never data leakage). To achieve complete tag isolation across tenants in Redis, assign each tenant a dedicated Redis database or connection prefix.
Upgrade Guide
Atomic Cache adheres to Semantic Versioning:
| Release | Change | Impacted Workloads | Recommended Action |
|---|---|---|---|
v1.6.0 (2026-11-14) |
Stale-While-Revalidate (flexible), Query Pagination/Aggregation Macros, and Multi-Runtime Resiliency |
All workloads. | Added AtomicCache::flexible() for non-blocking background revalidation, query macros atomicCachePaginate, atomicCacheSimplePaginate, atomicCacheCount, atomicCacheExists, separated $perUser and $tags in HasAtomicCache::cache(), and fixed container resolution in CLI/Queue/stateless environments. |
v1.5.0 (2026-10-28) |
Transaction Guard, Scoped Query Macro, $cacheIgnoreColumns, Strict Mode, and Universal OCC | All workloads. | OCC now operates universally via atomic UUID version tokens across all drivers. Added Transaction Guard (bypass_during_transactions), $cacheIgnoreColumns for counter updates, Strict Mode validation, scope: query macro parameter, and AtomicCache::invalidating() wrapper. |
v1.4.3 |
BackedEnum Foreign Keys & Magic __isset Bypass |
Models using PHP 8.1+ Enums as foreign keys. | Foreign keys backed by enums are cleanly unwrapped before tag generation. Fixed reflection lookups to avoid triggering Eloquent magic __isset. |
v1.4.2 |
Transaction-Safe Deferred Parent Invalidation | Models using $cacheParents updated inside DB::transaction(...). |
Tags are resolved at event dispatch time before syncOriginal(), capturing old & new parent keys accurately after commit. |
v1.4.0 |
Smart Parent Invalidation & Architecture Linter | Applications declaring parent relationships ($cacheParents). |
Run php artisan atomic-cache:check to audit Eloquent relationship caching health. |
v1.3.8 |
Optimistic Concurrency Control (OCC) & Query DoS Limits | Write-heavy models and long filter query strings. | Cache computation aborted if tags changed mid-flight. Requests exceeding 20 query parameters bypass cache to prevent DoS. |
v1.3.7 |
Chunk Generation IDs & Tag-Scoped Flush | Transparent chunking users. | Chunk keys utilize {key}:__chunk__:{generation}:{i} to eliminate torn reads. Old chunk formats remain backwards-compatible. |
v1.3.4 |
Opt-in Deduplication & Event Hooks | AutoClearsCache now listens to created, updated, deleted, restored. |
increment() and decrement() trigger invalidation. Deduplication is opt-in via ATOMIC_CACHE_DEDUPLICATION_ENABLED=true. |
Testing
Run the test suite using PHPUnit:
composer test # or vendor/bin/phpunit
Credits & License
- Kazi Omar Faruk (@kaziomarsh24)
- Built with high-performance distributed architecture for modern Laravel applications.
- Licensed under the MIT License. Please see License File for more information.