Download the PHP package skaisser/laravel-cache-cascade without Composer

Laravel Cache Cascade

Never lose your cached data again. Laravel Cache Cascade provides bulletproof caching with automatic fallback through multiple storage layers. When Redis goes down, your app keeps running. When files get corrupted, data loads from the database. When the database is empty, seeders run automatically.

🚀 Perfect for: SaaS settings, CMS content, API responses, feature flags, and any rarely-changing data that must always be available.

Why This Package Exists

Ever had Redis crash and take your app down because all your cached settings disappeared? Or struggled with cache invalidation when your database updates? Laravel's built-in cache is great, but it has limitations:

• Single point of failure - When your cache driver fails, your app fails
• No automatic persistence - Cache expires and you have to rebuild from scratch
• Manual invalidation - Database changes don't automatically update the cache
• No built-in fallback - You need to write try-catch blocks everywhere

Laravel Cache Cascade solves these problems by creating a resilient caching system that automatically falls back through multiple storage layers and keeps them in sync.

Laravel Cache vs Cache Cascade

Features

• 🏗️ Multi-layer Caching: Automatic fallback chain (Cache → File → Database → Auto-seeding)
• 🔒 Visitor Isolation: Optional visitor-specific cache keys for enhanced security
• 🌱 Auto-seeding: Automatically seed data from seeders when not found
• 📁 File Storage: Persistent file-based caching layer
• 🔄 Flexible Configuration: Customize fallback order and behavior
• 🏷️ Cache Tagging: Support for tagged cache operations
• ⚡ High Performance: Request-level caching to minimize database queries
• ♻️ Automatic Invalidation: Database changes automatically refresh cache and file layers
• 🎯 Model Integration: Trait for automatic cache management in Eloquent models

Installation

Install the package via Composer:

Configuration

Publish the configuration file:

This will create a config/cache-cascade.php file where you can customize the package settings.

Key Configuration Options

Usage

Basic Usage

Remember Pattern

Visitor Isolation

Enable visitor-specific caching to prevent data leakage between users:

Working with Models

The package can automatically load data from Eloquent models and seed if empty:

How It Works

Fallback Chain

When you request data, the package tries each storage layer in order:

1. Cache Layer: Fast in-memory storage (Redis/Memcached)
2. File Layer: Persistent file storage for rarely-changing data
3. Database Layer: Load from Eloquent models
4. Auto-seeding: Run seeders if no data exists

File Storage Format

Files are stored in PHP format by default:

Automatic Model Detection

The package intelligently detects models based on the cache key:

• 'faqs' → App\Models\Faq
• 'settings' → App\Models\Setting
• 'categories' → App\Models\Category

Cache Invalidation

One of the most important features is automatic cache invalidation when database data changes. The package provides multiple ways to handle this:

Manual Invalidation

Automatic Model Invalidation

Use the CascadeInvalidation trait in your Eloquent models for automatic cache invalidation:

Now when you update the model, the cache is automatically refreshed:

Invalidation Events

The trait automatically invalidates cache on:

• Model creation (created)
• Model updates (updated)
• Model deletion (deleted)
• Model restoration (restored - for soft deletes)

Manual Model Refresh

Advanced Usage

For advanced features like custom storage drivers, performance optimization, multi-tenant support, and more, see the Advanced Usage Guide.

Quick Examples

Custom Transformations

Skip Database Layer

Cache Tags (Redis/Memcached only)

Comprehensive Examples

Real-World Usage Patterns

E-commerce Settings

Multi-tenant SaaS Application

CMS Content Management

API Response Caching

Feature Flags & Configuration

Laravel Integration

Artisan Commands

The package provides several Artisan commands:

Integration with Laravel Commands

cache:clear

By default, running php artisan cache:clear will also clear all cascade cache. You can disable this:

config:cache

Dynamic cascade files are excluded from config:cache by default. If you need to check which files would be cached:

Logging & Debugging

Enable detailed logging to debug cache behavior:

Or configure in the config file:

View runtime statistics:

Example log output:

Real-World Use Cases

🏢 SaaS Applications

Problem: Your app stores tenant settings, feature flags, and subscription plans in cache. When Redis restarts, all tenants experience errors.

Solution: Cache Cascade ensures settings persist in files and auto-reload from database:

📰 Content Management Systems

Problem: Your CMS caches articles, menus, and widgets. Cache invalidation is a nightmare when editors update content.

Solution: Use the trait for automatic invalidation:

🌐 API Gateway / Microservices

Problem: You cache API responses but need fallback when the cache server is unreachable.

Solution: Cache with file backup for critical endpoints:

🎛️ Feature Flags & Configuration

Problem: Feature flags must always be available but can change dynamically.

Solution: Database-backed cache with instant updates:

🏪 E-commerce Settings

Problem: Payment gateways, shipping rates, and tax rules must never fail to load.

Solution: Multi-layer protection with auto-seeding:

Testing

Testing Your Code with CacheCascade::fake()

The package provides a powerful fake implementation for easy testing:

Available test assertions:

• assertCalled($method, $arguments) - Verify method was called
• assertNotCalled($method) - Verify method wasn't called
• assertHas($key) - Check if cache has key
• assertMissing($key) - Check if cache doesn't have key
• calledCount($method) - Get number of calls
• reset() - Clear fake data between tests

See Testing Documentation for comprehensive examples.

Running Package Tests

Run the test suite:

Run tests with code coverage:

Test Coverage

The package maintains 90.13% code coverage with comprehensive tests for:

• ✅ Core CacheCascadeManager functionality
• ✅ Console commands (refresh, clear, stats)
• ✅ Model trait integration
• ✅ Facade implementation
• ✅ Testing utilities (CacheCascadeFake)
• ✅ Helper classes
• ✅ Error handling and edge cases
• ✅ Visitor isolation
• ✅ Auto-seeding functionality

Performance

Benchmarks

Cache Cascade adds minimal overhead while providing maximum reliability:

*Write operations update all layers for reliability

Optimization Tips

1. Use appropriate TTLs - Longer TTLs reduce database hits
2. Enable visitor isolation selectively - Only for user-specific data
3. Use file storage for rarely-changing data - Config, settings, etc.
4. Batch operations when possible - Reduce write overhead

Security

• Visitor Isolation: Prevents cache poisoning and data leaks between users
• File Permissions: Ensure proper permissions (755) on cache directories
• Sensitive Data: Consider encryption for sensitive cached data
• Input Validation: Cache keys are sanitized to prevent directory traversal

See Security Best Practices for detailed guidelines.

Documentation

• 📖 API Reference - Complete method documentation
• 🧪 Testing Guide - Testing strategies and examples
• 🔒 Security Best Practices - Security considerations
• 🚀 Advanced Usage - Performance optimization and advanced patterns
• 🔧 Troubleshooting - Common issues and solutions

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please see Contributing Guide for details.

Credits

• Shirleyson Kaisser
• All Contributors

License

The MIT License (MIT). Please see License File for more information.