fxcjahid/laravel-eloquent-cache-magic

A lightweight Laravel package for automatic Eloquent query caching with zero-code auto-cache, Redis/Memcached tag support, and automatic cache invalidation

1.0.0 2025-10-20 06:13 UTC

Requires

• php: >=8.0
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• predis/predis: ^2.0|^3.0

Requires (Dev)

• mockery/mockery: ^1.5
• orchestra/testbench: ^7.0|^8.0|^9.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpunit/phpunit: ^9.5|^10.0|^11.0

Suggests

• ext-memcached: Required for Memcached cache driver with tag support
• predis/predis: Required for Redis cache driver with tag support (^2.0)

MIT

• FXC Jahid

• redis
• performance
• cache
• memcached
• tags
• optimization
• laravel
• eloquent
• invalidation
• query-builder
• auto-cache
• automatic-caching
• zero-configuration

README

A lightweight Laravel package that adds intelligent caching to your Eloquent queries with zero effort. Features include automatic cache invalidation, Redis/Memcached tag support, and flexible caching options!

📖 Read Complete Documentation - Everything you need to know in one place

✨ Features

• 🚀 Zero Configuration - Works out of the box with sensible defaults
• 🎉 Automatic Query Caching - All queries automatically cached without code changes!
• 🏷️ Cache Tags Support - Full support for Redis and Memcached tagged caching
• 🔄 Automatic Cache Invalidation - Cache automatically clears on model create, update, delete
• 🔧 Flexible API - Multiple ways to configure caching per query
• 🌐 Multi-Driver Support - Works with Redis, Memcached, File, Database drivers
• 🧪 Fully Tested - Comprehensive test coverage with PHPUnit and Pest
• 👤 Auto User/Guest Tags - Automatic user-specific cache isolation
• 🚫 doNotCache() Method - Disable caching for specific queries (DataTables compatible)
• 🎯 Helper Functions - Convenient global functions for cache operations

📋 Requirements

• PHP 8.0 - 8.4
• Laravel 10.0 - 12.0
• Redis or Memcached (optional, for tag support)

📦 Installation

composer require fxcjahid/laravel-eloquent-cache-magic

Optional: Publish Configuration

php artisan vendor:publish --tag=cache-magic-config

Recommended: Setup Redis for Tag Support

composer require predis/predis

CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Also update config/database.php

'redis' => [
    'client' => env('REDIS_CLIENT', 'predis'),
]

🚀 Quick Start

🎉 Automatic Query Caching

With auto-cache enabled, ALL your queries are automatically cached without any code changes:

use App\Models\User;
use App\Models\Product;

// These queries are AUTOMATICALLY cached (no ->cache() needed!)
$users = User::all();                          // Auto-cached!
$product = Product::find(1);                   // Auto-cached!
$count = User::where('active', true)->count(); // Auto-cached!

// Bypass auto-cache when you need fresh data
$freshUsers = User::withoutCache()->get();     // Skip cache
$freshProduct = Product::fresh()->find(1);     // Skip cache

// Disable auto-cache for specific models
class Order extends Model {
    use CacheableTrait;
    protected $autoCache = false;  // Disable auto-cache for this model
}

Manual Caching (Traditional Method)

You can still manually control caching with the ->cache() method:

// Manually cache the query
$users = User::where('active', true)->cache()->get();

// Cache for specific duration (in seconds)
$users = User::where('active', true)->cache(3600)->get(); // 1 hour

// Cache with tags (Redis/Memcached only)
$users = User::where('active', true)
    ->cache()
    ->tags(['users', 'active'])
    ->get();

// Clear cache by tags
Cache::tags(['users'])->flush(); // Only clears 'users' tagged cache

Model Integration

use Illuminate\Database\Eloquent\Model;
use Fxcjahid\LaravelEloquentCacheMagic\Traits\CacheableTrait;

class Product extends Model
{
    use CacheableTrait;

    protected $cacheExpiry = 7200; // 2 hours
    protected $cacheTags = ['products'];
}

🎯 Key Features Explained

🎉 Automatic Query Caching

Enable automatic caching for ALL queries without changing your code:

// In config/cache-magic.php
'auto_cache' => [
    'enabled' => true,              // Enable auto-caching
    'ttl' => 3600,                  // Default 1 hour
    'aggregate_ttl' => 300,         // 5 min for count/sum/avg
    'find_ttl' => 7200,             // 2 hours for find()
],

Once enabled, all your existing queries are automatically cached:

// These are ALL automatically cached now!
User::all();                        // Cached for 1 hour
Product::find($id);                 // Cached for 2 hours
Order::count();                     // Cached for 5 minutes
Invoice::where('paid', true)->get(); // Cached for 1 hour

// Need fresh data? Bypass cache:
User::withoutCache()->all();        // Direct from database
Product::fresh()->find($id);        // Direct from database

Cache Tags - Smart Invalidation

// Cache with tags for smart invalidation
$products = Product::where('category', 'electronics')
    ->cache()
    ->tags(['products', 'electronics'])
    ->get();

// Clear all electronics products
Cache::tags(['electronics'])->flush();

// Clear all products
Cache::tags(['products'])->flush();

Automatic Cache Invalidation

class Product extends Model
{
    use CacheableTrait;

    // Cache automatically clears when model is updated/deleted
    protected $cacheTags = ['products'];

    // Dynamic tags based on attributes
    public function dynamicCacheTags(): array
    {
        return [
            'category:' . $this->category_id,
            'brand:' . $this->brand_id,
        ];
    }
}

User/Guest Isolation

Automatically isolate cache by user or guest session:

// In config/cache-magic.php
'auto_user_tags' => [
    'enabled' => true,
    'guest_fallback' => 'session', // Options: 'session', 'ip', 'unique'
],

📊 Console Commands

# Clear cache by tags
php artisan cache-magic:clear --tags=products

# Clear cache by model
php artisan cache-magic:clear --model=Product

# Clear all cache
php artisan cache-magic:clear --all

🔧 Helper Functions

// Cache a callback result
$users = cache_remember(['ttl' => 3600, 'tags' => ['users']], function() {
    return User::all();
});

// Clear cache by tags
cache_clear_tags(['products', 'electronics']);

// Clear cache by model
cache_clear_model(Product::class);

// Clear user-specific cache
cache_clear_user($userId);

// Clear guest cache
cache_clear_guest($guestId);

// Check if cache supports tags
if (cache_supports_tags()) {
    // Use tag-based caching
}

📖 Complete Documentation

Read the complete documentation for comprehensive details on:

• ✅ Installation and configuration
• ✅ All query methods and parameters
• ✅ Cache tags explained with examples
• ✅ Model integration guide
• ✅ Console commands usage
• ✅ Helper functions
• ✅ Advanced features
• ✅ Troubleshooting guide

🧪 Testing

# Run tests
vendor/bin/pest

# With coverage
vendor/bin/pest --coverage

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This package is open-sourced software licensed under the MIT license.

👨‍💻 Author

FXC Jahid

• GitHub: @fxcjahid
• Email: [e-mail]

🌟 Support

If you find this package helpful, please give it a ⭐ on GitHub!