📦 Installation

Requirements

• PHP 8.1 or higher
• Laravel 8.0 or higher (including Laravel 12+)
• Any Laravel-supported cache driver (Redis, File, Database, Array, Memcached)

Installation Steps

composer require iazaran/smart-cache

Configuration (Optional)

SmartCache works out-of-the-box with sensible defaults. For advanced customization:

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

 [
        'compression' => 1024 * 50, // 50KB - compress data larger than this
        'chunking' => 1024 * 100,   // 100KB - chunk arrays larger than this
    ],

    /*
    |--------------------------------------------------------------------------
    | Strategies
    |--------------------------------------------------------------------------
    |
    | Configure which optimization strategies are enabled and their options.
    |
    */
    'strategies' => [
        'compression' => [
            'enabled' => true,
            'level' => 6, // 0-9 (higher = better compression but slower)
        ],
        'chunking' => [
            'enabled' => true,
            'chunk_size' => 1000, // Items per chunk for arrays/collections
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Performance Monitoring
    |--------------------------------------------------------------------------
    |
    | Enable performance monitoring to track cache hit/miss ratios,
    | optimization impact, and operation durations.
    |
    */
    'monitoring' => [
        'enabled' => true,
        'metrics_ttl' => 3600, // How long to keep metrics in cache (seconds)
        'recent_entries_limit' => 100, // Number of recent operations to track
    ],

    /*
    |--------------------------------------------------------------------------
    | Performance Warnings
    |--------------------------------------------------------------------------
    |
    | Configure thresholds for performance warnings and recommendations.
    |
    */
    'warnings' => [
        'hit_ratio_threshold' => 70, // Warn if hit ratio below this percentage
        'optimization_ratio_threshold' => 20, // Warn if optimization usage below this
        'slow_write_threshold' => 0.1, // Warn if writes slower than this (seconds)
    ],

    /*
    |--------------------------------------------------------------------------
    | Cache Drivers
    |--------------------------------------------------------------------------
    |
    | Configure which cache drivers should use which optimization strategies.
    | Set to null to use the global strategies configuration.
    |
    */
    'drivers' => [
        'redis' => null, // Use global settings
        'file' => [
            'compression' => true,
            'chunking' => true,
        ],
        'memcached' => [
            'compression' => false, // Memcached has its own compression
            'chunking' => true,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Fallback
    |--------------------------------------------------------------------------
    |
    | Configure fallback behavior if optimizations fail or are incompatible.
    |
    */
    'fallback' => [
        'enabled' => true,
        'log_errors' => true,
    ],
];

Service Provider

SmartCache automatically registers its service provider. No additional configuration is needed for Laravel 8+.

💻 Basic Usage

Familiar Laravel API

SmartCache works exactly like Laravel's built-in Cache facade. Your existing code works unchanged:

use SmartCache\Facades\SmartCache;

// Basic caching (just like Laravel Cache)
SmartCache::put('user_data', $userData, 3600);
$userData = SmartCache::get('user_data');

// Helper function (just like cache() helper)
smart_cache(['products' => $products], 3600);
$products = smart_cache('products');

// Remember pattern (just like Cache::remember)
$users = SmartCache::remember('users', 3600, function() {
    return User::all();
});

// Check if key exists
if (SmartCache::has('users')) {
    $users = SmartCache::get('users');
}

// Forget a key
SmartCache::forget('users');

// Clear all cache
SmartCache::flush();

Automatic Optimization

SmartCache automatically optimizes your data when beneficial:

// Large array - automatically chunked
$largeArray = range(1, 10000);
SmartCache::put('large_data', $largeArray, 3600);
// Data is automatically chunked for better performance

// Large string - automatically compressed
$largeString = str_repeat('Hello World! ', 1000);
SmartCache::put('large_text', $largeString, 3600);
// Data is automatically compressed to save space

Cache Tags

Group related cache entries for easy management:

// Store with tags
SmartCache::tags(['users', 'profiles'])->put('user_1', $user1, 3600);
SmartCache::tags(['users', 'profiles'])->put('user_2', $user2, 3600);

// Clear all cache with specific tags
SmartCache::tags(['users'])->flush(); // Clears both user_1 and user_2

// Clear cache with multiple tags
SmartCache::tags(['users', 'profiles'])->flush();

Cache Locking

Prevent cache stampede with atomic locks:

$lock = SmartCache::lock('expensive_operation', 10);

if ($lock->get()) {
    try {
        // Perform expensive operation
        $result = expensiveOperation();
        SmartCache::put('expensive_result', $result, 3600);
    } finally {
        $lock->release();
    }
} else {
    // Wait for the lock to be released
    $result = SmartCache::get('expensive_result');
}

⚡ Optimization Features

Intelligent Compression

SmartCache automatically compresses large data to reduce storage requirements:

// Large data automatically compressed
$largeData = [
    'products' => Product::with('images', 'reviews')->get(),
    'categories' => Category::with('children')->get(),
    'settings' => Setting::all()
];

SmartCache::put('catalog_data', $largeData, 3600);
// Automatically compressed with gzip, saving up to 70% space

Smart Chunking

Large arrays and objects are automatically chunked for better performance:

// Large array automatically chunked
$users = User::with('profile', 'posts')->get(); // 10,000+ records
SmartCache::put('all_users', $users, 3600);
// Automatically split into manageable chunks

Strategy Selection

SmartCache automatically chooses the best optimization strategy:

Configuration Options

// config/smart-cache.php
return [
    'thresholds' => [
        'compression' => 1024 * 50, // 50KB
        'chunking' => 1024 * 100,   // 100KB
    ],
    
    'strategies' => [
        'compression' => [
            'enabled' => true,
            'level' => 6, // gzip compression level (1-9)
        ],
        'chunking' => [
            'enabled' => true,
            'chunk_size' => 1000, // Items per chunk
        ],
    ],
    
    'monitoring' => [
        'enabled' => true,
        'metrics_ttl' => 3600,
    ],
];

Performance Impact

🌊 SWR Patterns (Laravel 12+)

What is SWR?

SWR (Stale-While-Revalidate) is a caching strategy that serves stale data immediately while refreshing it in the background. This provides:

• ⚡ Instant responses - Users see data immediately
• 🔄 Fresh data - Background updates ensure data stays current
• 🚫 No cache stampede - Prevents multiple simultaneous requests

Basic SWR Usage

// SWR: Serve stale data while refreshing in background
$apiData = SmartCache::swr('github_repos', function() {
    return Http::get('https://api.github.com/user/repos')->json();
}, 300, 900); // 5min fresh, 15min stale

Extended Stale Serving

For slowly changing data, serve stale data for extended periods:

// Extended stale serving for site configuration
$siteConfig = SmartCache::stale('site_config', function() {
    return Config::fromDatabase();
}, 3600, 86400); // 1hour fresh, 24hour stale

Refresh-Ahead Caching

Proactively refresh cache before expiration:

// Refresh-ahead for expensive computations
$analytics = SmartCache::refreshAhead('daily_analytics', function() {
    return Analytics::generateReport();
}, 1800, 300); // 30min TTL, 5min refresh window

Real-World Examples

API Gateway Cache

class ApiController
{
    public function getProducts()
    {
        return SmartCache::swr('api_products', function() {
            return Product::with('images', 'reviews')->get();
        }, 300, 900); // 5min fresh, 15min stale
    }
    
    public function getUserProfile($userId)
    {
        return SmartCache::stale("user_profile_{$userId}", function() use ($userId) {
            return User::with('profile', 'settings')->find($userId);
        }, 1800, 3600); // 30min fresh, 1hour stale
    }
}

E-commerce Product Recommendations

class RecommendationService
{
    public function getRecommendations($userId)
    {
        return SmartCache::refreshAhead(
            "recommendations_{$userId}",
            function() use ($userId) {
                return $this->aiEngine->generateRecommendations($userId);
            },
            3600, 600 // 1hour TTL, 10min refresh window
        );
    }
}

📊 Performance Monitoring

Real-Time Metrics

Get comprehensive performance metrics about your cache usage:

// Get all performance metrics
$metrics = SmartCache::getPerformanceMetrics();

/*
Returns:
[
    'cache_efficiency' => [
        'hit_ratio' => 0.943,
        'miss_ratio' => 0.057,
        'total_requests' => 1000
    ],
    'optimization_impact' => [
        'compression_savings' => 0.68,
        'chunking_benefits' => 0.23,
        'total_size_reduction' => 0.72
    ],
    'operation_timing' => [
        'average_get_time' => 0.023,
        'average_put_time' => 0.045,
        'total_operations' => 5000
    ]
]
*/

Health Analysis

Get automated analysis and recommendations:

// Automated performance analysis
$analysis = SmartCache::analyzePerformance();

/*
Returns:
[
    'overall_health' => 'good', // good, warning, critical
    'recommendations' => [
        'Consider increasing cache TTL for frequently accessed data',
        'Enable compression for large text data'
    ],
    'issues' => [],
    'score' => 85
]
*/

HTTP Command Execution

Manage cache via HTTP API (perfect for web-based admin panels):

// Get available commands
$commands = SmartCache::getAvailableCommands();

// Execute commands via HTTP
$status = SmartCache::executeCommand('status');
$clearResult = SmartCache::executeCommand('clear');
$specificClear = SmartCache::executeCommand('clear', [
    'key' => 'expensive_computation',
    'force' => true
]);

CLI Commands

# Quick status overview
php artisan smart-cache:status

# Detailed analysis with recommendations
php artisan smart-cache:status --force

# Clear all SmartCache managed keys
php artisan smart-cache:clear

# Clear specific key
php artisan smart-cache:clear expensive_api_call

# Force clear any cache key
php artisan smart-cache:clear --force

🔧 Advanced Features

Smart Cache Invalidation

Dependency Tracking

Create cache hierarchies where invalidating a parent clears all children:

// Create cache dependencies
SmartCache::dependsOn('user_posts', 'user_profile');
SmartCache::dependsOn('user_stats', 'user_profile');

// Invalidate parent - children cleared automatically
SmartCache::invalidate('user_profile');
// This will also clear 'user_posts' and 'user_stats'

Pattern-Based Invalidation

Clear cache entries using wildcards and regex patterns:

// Pattern-based clearing
SmartCache::flushPatterns([
    'user_*',           // All user keys
    'api_v2_*',         // All API v2 cache
    '/product_\d+/'     // Regex: product_123, product_456
]);

Model Auto-Invalidation

Automatically clear cache when Eloquent models change:

use SmartCache\Traits\CacheInvalidation;

class User extends Model
{
    use CacheInvalidation;
    
    public function getCacheKeysToInvalidate(): array
    {
        return [
            "user_{$this->id}_profile",
            "user_{$this->id}_posts",
            'users_list_*'
        ];
    }
}

// Cache automatically cleared when user changes!
$user = User::find(1);
$user->update(['name' => 'New Name']); // Cache cleared automatically

Custom Optimization Strategies

Create custom optimization strategies for your specific needs:

use SmartCache\Contracts\OptimizationStrategy;

class JsonCompressionStrategy implements OptimizationStrategy
{
    public function shouldApply(mixed $value, array $context = []): bool
    {
        return is_array($value) && 
               json_encode($value, JSON_UNESCAPED_UNICODE) !== false &&
               strlen(json_encode($value)) > 10240; // 10KB threshold
    }
    
    public function optimize(mixed $value, array $context = []): mixed
    {
        $json = json_encode($value, JSON_UNESCAPED_UNICODE);
        return [
            '_sc_json_compressed' => true,
            'data' => gzcompress($json, 9)
        ];
    }
    
    public function restore(mixed $value, array $context = []): mixed
    {
        if (is_array($value) && ($value['_sc_json_compressed'] ?? false)) {
            return json_decode(gzuncompress($value['data']), true);
        }
        return $value;
    }
    
    public function getIdentifier(): string
    {
        return 'json_compression';
    }
}

// Register your custom strategy
SmartCache::addStrategy(new JsonCompressionStrategy());

📚 Complete API Reference

🔧 Basic Cache Operations

$users = SmartCache::get('users', []);
$config = SmartCache::get('app_config', collect());

SmartCache::put('users', $users, 3600);
SmartCache::put('config', $config, now()->addHours(2));

$users = SmartCache::remember('users', 3600, function() {
    return User::with('profile')->get();
});

if (SmartCache::has('users')) {
    $users = SmartCache::get('users');
}

SmartCache::forget('users');

🌊 SWR Patterns (Laravel 12+)

$apiData = SmartCache::swr('github_repos', function() {
    return Http::get('https://api.github.com/user/repos')->json();
}, 300, 900); // 5min fresh, 15min stale

$siteConfig = SmartCache::stale('site_config', function() {
    return Config::fromDatabase();
}, 3600, 86400); // 1hour fresh, 24hour stale

$analytics = SmartCache::refreshAhead('daily_analytics', function() {
    return Analytics::generateReport();
}, 1800, 300); // 30min TTL, 5min refresh window

🔗 Cache Invalidation & Dependencies

SmartCache::tags(['users', 'profiles'])->put('user_1', $user1, 3600);
SmartCache::tags('products')->put('product_123', $product, 1800);

SmartCache::flushTags(['users']); // Clear all user-related cache

SmartCache::dependsOn('user_posts', 'user_profile');

$cleared = SmartCache::flushPatterns([
    'user_*',           // All user keys
    'api_v2_*',         // All API v2 cache
    '/product_\d+/'     // Regex: product_123, product_456
]);

📊 Performance Monitoring

$metrics = SmartCache::getPerformanceMetrics();
/*
Returns:
[
    'cache_efficiency' => [
        'hit_ratio' => 0.943,
        'miss_ratio' => 0.057,
        'total_requests' => 1000
    ],
    'optimization_impact' => [
        'compression_savings' => 0.68,
        'chunking_benefits' => 0.23,
        'total_size_reduction' => 0.72
    ]
]
*/

$analysis = SmartCache::analyzePerformance();
/*
Returns:
[
    'overall_health' => 'good', // good, warning, critical
    'recommendations' => [
        'Consider increasing cache TTL for frequently accessed data'
    ],
    'score' => 85
]
*/

$status = SmartCache::executeCommand('status');
$result = SmartCache::executeCommand('clear', ['key' => 'specific_key']);

🛠️ Cache Management

SmartCache::clear(); // Clear all SmartCache managed keys

$keys = SmartCache::getManagedKeys();
foreach ($keys as $key) {
    echo "Managed key: {$key}\n";
}

🔧 Helper Functions

// Get SmartCache instance
$cache = smart_cache();

// Get value
$users = smart_cache('users');

// Set value
smart_cache('users', $users, 3600);

💻 CLI Commands

# Basic status overview
php artisan smart-cache:status

# Detailed analysis with recommendations
php artisan smart-cache:status --force

# Clear all SmartCache managed keys
php artisan smart-cache:clear

# Clear specific key
php artisan smart-cache:clear user_profile_123

# Force clear any cache key
php artisan smart-cache:clear --force

🧪 Testing & Validation

Complete Test Controller

We've created a comprehensive test controller that validates all SmartCache features in a production-like environment. This controller tests 20+ features and provides detailed performance metrics.

Controller Implementation

Here's a sample of the comprehensive test controller structure:

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use SmartCache\Facades\SmartCache;

class TestSmartCacheDirectlyController extends Controller
{
    public function testSmartCacheFeatures()
    {
        $packageInfo = ['version' => '1.4.2', 'features_tested' => 20];
        $tests = [];

        try {
            // Test 1: Basic Operations
            $tests['basic_operations'] = $this->testBasicOperations();
            
            // Test 2: Compression (2000+ records)
            $tests['compression_test'] = $this->testCompressionFeature();
            
            // Test 3: Chunking (5000+ items)
            $tests['chunking_test'] = $this->testChunkingFeature();
            
            // Test 4: Helper Functions
            $tests['helper_function'] = $this->testHelperFunctions();
            
            // Test 5: SWR Patterns (Laravel 12+)
            if (version_compare(app()->version(), '12.0', '>=')) {
                $tests['swr_patterns'] = $this->testSWRPatterns();
            }
            
            // Test 6: Cache Invalidation & Tags
            $tests['cache_invalidation'] = $this->testCacheInvalidation();
            
            // Test 7: Performance Monitoring
            $tests['performance_monitoring'] = $this->testPerformanceMonitoring();
            
            // Test 8: Advanced Features (remember, locking)
            $tests['advanced_features'] = $this->testAdvancedFeatures();

            return response()->json([
                'message' => 'SmartCache feature tests completed',
                'package_info' => $packageInfo,
                'tests' => $tests,
                'overall_status' => 'success'
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'message' => 'SmartCache test failed',
                'error' => $e->getMessage()
            ], 500);
        }
    }

    private function testBasicOperations()
    {
        $testData = ['data' => 'test_value', 'number' => 123, 'array' => range(1, 10)];

        // Test facade operations
        SmartCache::put('test_facade', $testData, 300);
        $facadeResult = SmartCache::get('test_facade');
        
        // Test helper operations  
        smart_cache(['test_helper' => $testData], 300);
        $helperResult = smart_cache('test_helper');

        return [
            'status' => 'success',
            'facade_results' => [
                'data_integrity' => $testData === $facadeResult,
                'has_key' => SmartCache::has('test_facade')
            ],
            'helper_results' => [
                'data_integrity' => $testData === $helperResult,
                'has_key' => SmartCache::has('test_helper')
            ],
            'both_methods_working' => ($testData === $facadeResult && $testData === $helperResult)
        ];
    }

    // ... Additional test methods for compression, chunking, SWR patterns, etc.
    // See complete implementation in the GitHub Gist
}

How to Use the Test Controller

1. Installation

Add this controller to your Laravel application:

php artisan make:controller Api/V1/TestSmartCacheDirectlyController

Route::get('/test-smart-cache', [TestSmartCacheDirectlyController::class, 'testSmartCacheFeatures']);

2. Running the Tests

Access the endpoint to run comprehensive tests:

# Via HTTP request
curl http://your-app.com/api/test-smart-cache

# Or via browser
http://your-app.com/api/test-smart-cache

3. Understanding the Results

The test controller returns a comprehensive JSON response with detailed results:

{
  "message": "SmartCache feature tests completed",
  "package_info": {
    "version": "1.4.2",
    "features_tested": 20
  },
  "tests": {
    "basic_operations": {
      "status": "success",
      "both_methods_working": true,
      "facade_results": { "data_integrity": true, "has_key": true },
      "helper_results": { "data_integrity": true, "has_key": true }
    },
    "compression_test": {
      "status": "success",
      "original_count": 2000,
      "estimated_size_kb": 2207.29,
      "both_methods_successful": true
    },
    "chunking_test": {
      "status": "success", 
      "original_count": 5000,
      "data_matches": true
    },
    "performance_monitoring": {
      "status": "success",
      "monitoring_working": true
    }
    // ... additional test results
  },
  "overall_status": "success"
}

What Each Test Validates

Production Validation

This test controller has been used to validate SmartCache in production environments with excellent results:

For the complete, latest version of this test controller, visit: GitHub Gist - SmartCache Test Controller

🔄 Migration Guide

From Laravel Cache

SmartCache is 100% compatible with Laravel's built-in Cache facade. Migration is simple:

composer require iazaran/smart-cache

// Old
use Illuminate\Support\Facades\Cache;

// New
use SmartCache\Facades\SmartCache;

// Old
Cache::put('key', $value, 3600);
$value = Cache::get('key');

// New (works exactly the same)
SmartCache::put('key', $value, 3600);
$value = SmartCache::get('key');

Gradual Migration

You can migrate gradually by using both facades:

use Illuminate\Support\Facades\Cache;
use SmartCache\Facades\SmartCache;

// Keep existing code unchanged
Cache::put('old_key', $value, 3600);

// Use SmartCache for new features
SmartCache::put('new_key', $value, 3600);
SmartCache::swr('api_data', $callback, 300, 900);

Testing Migration

Test your migration with these commands:

# Test basic functionality
php artisan smart-cache:status

# Test with your application
php artisan tinker
>>> SmartCache::put('test', 'Hello World', 60);
>>> SmartCache::get('test');
=> "Hello World"

Rollback Plan

If you need to rollback, simply change the imports back:

# Change back to Laravel Cache imports in your code
# Then remove SmartCache package
composer remove iazaran/smart-cache