README

A Redis-based, fully automated, and scalable query cache layer for Laravel.

Lada Cache 6.x - a focused rewrite for Laravel 12 / 13 and PHP 8.3, addressing many long-standing issues and adding new features.

Table of Contents

• Features
• Version Compatibility
• Architecture
• Performance
• Why?
• Why only Redis?
• Installation
• Configuration
• Usage
• Console Commands
• Known Issues and Limitations
• Contributing
• License

Features

• 🚀 Fully automated query caching - no code changes required after setup
• 🧩 Granular invalidation - automatically invalidates only affected rows or tables
• 🧠 Transparent integration with Eloquent and Query Builder
• ⚡ Redis-backed - in-memory speed, cluster-ready, horizontally scalable
• 🧰 Laravel Debugbar integration - visualize cache hits, misses, and invalidations
• 🎛️ Fine-grained control - include or exclude tables from caching
• 🧱 Connection integration - DB queries pass through a Lada-aware connection subclass transparently

Version Compatibility

Architecture

Lada Cache integrates with Laravel’s database layer by registering a Lada-aware connection, which returns a custom query builder to intercept and cache SQL operations automatically.

Query lifecycle:

1. Intercept query → Reflector analyzes SQL, bindings, and affected tables.
2. Compute cache key → Based on SQL + parameters + database.
3. Lookup in Redis → If cached, return immediately.
4. Execute + store → If not cached, execute query and store result.
5. Auto-invalidate → On any insert, update, delete, or truncate.

The result is automatic, consistent caching across all database operations.

Performance

Real-world gains range from 5% to 95%, depending on how many and how complex your queries are. Typical Laravel apps see ~10–30% faster responses and a significant drop in DB load.

• Large payloads still cost to move/encode; e.g. a query returning ~500MB won’t get faster from caching alone.
• The more redundant and complex the queries per request, the bigger the benefit.
• Reduced database traffic can translate to lower infra cost and easier horizontal scaling.

Why?

• Database-heavy apps (especially with Eloquent) often repeat the same queries and not all are efficient.
• RDBMS internal caches (e.g., MySQL Query Cache) have hard limits:
  • Do not cache multi-table queries (joins)
  • Coarse invalidation (row change can evict a whole table)
  • Not distributed across DB servers
  • Poor scalability under load
• Laravel manual caching requires manual invalidation or time-based expiry.

Lada Cache provides automated, granular, distributed caching with transparent invalidation and scale-out via Redis.

Why only Redis?

• Requires in-memory storage for latency and throughput.
• Must be easily scalable and distributed.
• Needs tagging support for granular invalidation (Laravel Cache tags exist but are slow for this use case).

Therefore, Lada Cache builds directly on top of Laravel Redis. If you need another backend, contributions are welcome.

Installation

Install via Composer:

composer require spiritix/lada-cache

Lada Cache registers itself automatically via Laravel Package Discovery.

Then, publish the config file:

php artisan vendor:publish --provider="Spiritix\LadaCache\LadaCacheServiceProvider"

Finally, ensure all your Eloquent models include the trait:

use Spiritix\LadaCache\Database\LadaCacheTrait;

class Car extends Model
{
    use LadaCacheTrait;
}

💡 It’s best to add the trait in a shared BaseModel class that all models extend.

Configuration

After publishing the configuration file (see Installation), you will find a comprehensive config file at config/lada-cache.php.

This file allows you to fine-tune cache behavior, such as:

• Enabling or disabling Lada Cache globally
• Setting key prefixes and expiration times
• Defining which tables to include or exclude from caching
• Enabling Debugbar integration for cache inspection

The default configuration is already optimized for most Laravel applications, so you typically won’t need to modify it unless you want more granular control.

Usage

After installation, Lada Cache works automatically.
No code changes or caching calls are required - all database queries are transparently cached and invalidated.

You can control global behavior via .env:

LADA_CACHE_ACTIVE=true
LADA_CACHE_DEBUGBAR=true

Bypassing the cache per query

Use withoutCache() to opt a single query out of caching. The query skips both read caching and write invalidation, then continues through Laravel as usual:

// Eloquent
$user = User::where('id', $id)->withoutCache()->first();

// Query Builder
DB::table('users')->where('id', $id)->withoutCache()->update(['name' => 'New']);

This is useful for freshness-critical reads, diagnostics, or ad-hoc cache busting without touching the configuration.

Console Commands

# Flush all cached entries
php artisan lada-cache:flush

# Temporarily disable cache
php artisan lada-cache:disable

# Re-enable cache
php artisan lada-cache:enable

Known Issues and Limitations

• Multiple connections (DB::connection('foo')) are only supported when using Lada’s connection integration. Models defining $connection work automatically.
• Third-party packages with custom query builders may bypass caching.
• Complex SQL constructs such as UNION/INTERSECT/advanced expressions may not be fully reflected for row-level tagging; invalidation falls back to table-level tags.
• Raw SQL executed directly via the connection (e.g., DB::select(), DB::statement()) is not cached by design.
• Row-level tagging relies on standard single-column primary keys. Composite or unconventional primary keys fall back to table-level invalidation.

Contributing

Pull requests and issue reports are welcome!

• Follow PSR-12 coding style
• Add tests for all new features
• Submit via feature branches (no direct PRs from master)

License

Lada Cache is open-source software licensed under the MIT License.