README

A comprehensive, high-performance caching solution that provides multiple tiers of caching including OPcache, SHMOP, APCu, YAC, Redis, Memcached, SQLite, and File-based caching with automatic tier discovery, connection pooling, and failover support.

✨ Features

• 🚀 Multi-Tier Architecture: Automatically discovers and prioritizes cache tiers for optimal performance
• 🔄 Automatic Failover: Seamlessly falls back to available tiers when primary tiers fail
• ⚡ Connection Pooling: Efficient connection management for Redis and Memcached
• 🔧 Async Operations: Promise-based asynchronous cache operations with event loop support
• 🏥 Health Monitoring: Comprehensive health checks and alerting for all cache tiers
• 🔑 Smart Key Management: Intelligent key generation with tier-specific limitations handling
• 📊 Statistics & Monitoring: Detailed performance metrics and usage statistics
• 🛠️ CLI Tools: Command-line utilities for cache management and cleanup
• 🎯 Zero Configuration: Works out of the box with sensible defaults
• 🔒 Production Ready: Battle-tested with comprehensive error handling

🎯 Supported Cache Tiers

📦 Installation

Requirements

• PHP 8.1 or higher
• Composer
• At least one cache backend (File system is always available)

Installation via Composer

composer require kevinpirnie/kpt-cache

Optional Extensions

For maximum performance, install these PHP extensions:

# Redis support
pecl install redis

# Memcached support  
pecl install memcached

# APCu support
pecl install apcu

# YAC support
pecl install yac

🚀 Quick Start

Basic Usage

<?php
require_once 'vendor/autoload.php';

use KPT\Cache;

// Initialize the cache system
Cache::configure([
    'path' => '/var/cache/myapp',
    'prefix' => 'myapp:',
    'allowed_backends' => [ 'array', 'redis', 'memcached', 'opcache', 'shmop', 'file' ], // also: apcu, yac, sqlite
]);

// Store data (automatically uses best available tier)
Cache::set('user:123', $userData, 3600);

// Retrieve data
$userData = Cache::get('user:123');

// Delete data
Cache::delete('user:123');

// Clear all cache
Cache::clear();

Advanced Configuration

<?php
require_once 'vendor/autoload.php';

use KPT\Cache;

Cache::configure([
    'path' => '/var/cache/myapp',
    'prefix' => 'myapp:',
    'backends' => [
        'redis' => [
            'host' => 'localhost',
            'port' => 6379,
            'database' => 0,
            'persistent' => true
        ],
        'memcached' => [
            'host' => 'localhost', 
            'port' => 11211,
            'persistent' => true
        ],
    ]
]);

💡 Usage Examples

Tier-Specific Operations

// Store in specific tier
Cache::setToTier('key', $data, 3600, 'redis');

// Get from specific tier
$data = Cache::getFromTier('key', 'redis');

// Multi-tier operations
$results = Cache::setToTiers('key', $data, 3600, ['redis', 'memcached']);
$results = Cache::deleteFromTiers('key', ['redis', 'memcached']);

Async Operations

// Enable async support
Cache::enableAsync($eventLoop);

// Async operations with promises
Cache::getAsync('user:123')
    ->then(function($userData) {
        // Process user data
        return Cache::setAsync('processed:123', $processedData, 1800);
    })
    ->catch(function($error) {
        // Handle errors
        Logger::error('Cache error: ' . $error->getMessage());
    });

// Batch async operations
$promises = [
    Cache::getAsync('user:123'),
    Cache::getAsync('user:456'),
    Cache::getAsync('user:789')
];

CachePromise::all($promises)
    ->then(function($results) {
        // All users loaded
        foreach($results as $userData) {
            // Process each user
        }
    });

Health Monitoring

// Check overall health
$healthStatus = Cache::isHealthy();

// Check specific tier health
$isRedisHealthy = Cache::isTierHealthy('redis');

// Get detailed health information
$healthDetails = CacheHealthMonitor::checkAllTiers();

// Get performance statistics
$stats = Cache::getStats();

Key Management

// Namespaced keys
CacheKeyManager::setGlobalNamespace('myapp');
$key = CacheKeyManager::createNamespacedKey('user:123', 'session', 'redis');

// Analyze key generation
$keyInfo = CacheKeyManager::analyzeKey('very-long-key-name', 'memcached');

// Get tier limitations
$limitations = CacheKeyManager::getTierLimitations();

🔧 Configuration

Global Configuration

Cache::configure([
    // Global cache path (used by file, opcache, sqlite)
    'path' => '/var/cache/myapp',
    
    // Global key prefix  
    'prefix' => 'myapp:',
    
    // Backend-specific settings
    'backends' => [
        'redis' => [
            'host' => 'redis.example.com',
            'port' => 6379,
            'database' => 1,
            'prefix' => 'custom:',
            'persistent' => true,
            'retry_attempts' => 3
        ],
        'memcached' => [
            'host' => 'memcached.example.com',
            'port' => 11211,
            'persistent' => true
        ],
        'file' => [
            'path' => '/custom/cache/path',
            'permissions' => 0755
        ]
    ]
]);

Environment-Specific Configuration

// Development
if ($_ENV['APP_ENV'] === 'development') {
    Cache::configure([
        'path' => '/tmp/dev-cache',
        'prefix' => 'dev:'
    ]);
}

// Production
if ($_ENV['APP_ENV'] === 'production') {
    Cache::configure([
        'path' => '/var/cache/production',
        'prefix' => 'prod:',
        'backends' => [
            'redis' => [
                'host' => $_ENV['REDIS_HOST'],
                'port' => $_ENV['REDIS_PORT'],
                'database' => $_ENV['REDIS_DB']
            ]
        ]
    ]);
}

📊 Monitoring & Statistics

Performance Statistics

// Get comprehensive statistics
$stats = Cache::getStats();

/*
Returns:
[
    'opcache' => [
        'opcache_enabled' => true,
        'memory_usage' => [...],
        'statistics' => [...]
    ],
    'redis' => [
        'connected_clients' => 5,
        'memory_usage' => 45.2,
        'hit_rate' => 96.5
    ],
    'connection_pools' => [...],
    'tier_manager' => [...],
    'health_monitor' => [...]
]
*/

Health Monitoring

// Set up health monitoring
CacheHealthMonitor::initialize([
    'monitoring_enabled' => true,
    'check_interval' => 60,
    'alert_config' => [
        'log_alerts' => true,
        'email_alerts' => true,
        'callback_alerts' => function($tier, $message, $details) {
            // Custom alert handling
            SlackNotifier::send("Cache Alert: {$message}");
        }
    ]
]);

// Get health status
$health = CacheHealthMonitor::checkAllTiers();

🛠️ CLI Tools

The package includes CLI tools for cache management. After installation, you can access them in your vendor directory:

Cache Cleaner

# Clear all caches
php vendor/kevinpirnie/kpt-cache/cache/cleaner.php --clear_all

# Clear specific tier
php vendor/kevinpirnie/kpt-cache/cache/cleaner.php --clear_tier=redis

# Cleanup expired entries
php vendor/kevinpirnie/kpt-cache/cache/cleaner.php --cleanup

Integration with Cron

# Add to crontab for automatic cleanup
# Cleanup expired entries every hour
0 * * * * php /path/to/your/app/vendor/kevinpirnie/kpt-cache/cache/cleaner.php --cleanup

# Full cache clear daily at 3 AM
0 3 * * * php /path/to/your/app/vendor/kevinpirnie/kpt-cache/cache/cleaner.php --clear_all

🔍 Debugging & Troubleshooting

Debug Information

// Get comprehensive debug info
$debugInfo = Cache::debug();

// Check tier availability
$availableTiers = Cache::getAvailableTiers();

// Validate configuration
$configValidation = CacheConfig::validateGlobal();

// Get last errors
$lastError = Cache::getLastError();

Common Issues

Redis Connection Issues

// Test Redis connectivity
if (!Cache::isTierAvailable('redis')) {
    $error = Cache::getLastError();
    Logger::error("Redis unavailable: " . $error);
}

File Permission Issues

// Check cache path permissions
$pathInfo = Cache::getCachePathInfo();
if (!$pathInfo['is_writable']) {
    // Fix permissions or update path
    Cache::updateCachePath('/tmp/alternative-cache');
}

Memory Issues

// Monitor memory usage
$stats = Cache::getStats();
foreach (['opcache', 'apcu'] as $tier) {
    if (isset($stats[$tier]['memory_usage'])) {
        $usage = $stats[$tier]['memory_usage'];
        if ($usage > 90) {
            Logger::warning("{$tier} memory usage high: {$usage}%");
        }
    }
}

🚀 Performance Optimization

Best Practices

1. Tier Priority: Use faster tiers for frequently accessed data
2. Key Design: Use consistent, meaningful key patterns
3. TTL Strategy: Set appropriate expiration times
4. Connection Pooling: Enable for Redis/Memcached in high-traffic apps
5. Monitoring: Regular health checks and performance monitoring

Configuration for High Traffic

Cache::configure([
    'backends' => [
        'redis' => [
            'host' => 'redis-cluster.example.com',
            'persistent' => true,
            'retry_attempts' => 3,
            'connection_timeout' => 2
        ]
    ]
]);

// Enable connection pooling
CacheConnectionPool::configurePool('redis', [
    'min_connections' => 5,
    'max_connections' => 20,
    'idle_timeout' => 300
]);

🧪 Testing

Unit Testing Example

<?php
use PHPUnit\Framework\TestCase;
use KPT\Cache;

class CacheTest extends TestCase
{
    public function setUp(): void
    {
        Cache::configure(['path' => '/tmp/test-cache']);
    }

    public function testBasicOperations()
    {
        // Test set/get
        $this->assertTrue(Cache::set('test:key', 'test-value', 60));
        $this->assertEquals('test-value', Cache::get('test:key'));
        
        // Test delete
        $this->assertTrue(Cache::delete('test:key'));
        $this->assertFalse(Cache::get('test:key'));
    }

    public function testTierSpecificOperations()
    {
        if (Cache::isTierAvailable('redis')) {
            $this->assertTrue(
                Cache::setToTier('redis:test', 'redis-value', 60, 'redis')
            );
            $this->assertEquals(
                'redis-value', 
                Cache::getFromTier('redis:test', 'redis')
            );
        }
    }
}

📚 API Reference

Core Methods

Tier-Specific Methods

Async Methods

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Code Style: Follow PSR-12 coding standards
2. Documentation: Update documentation for new features
3. Testing: Add tests for new functionality
4. Backwards Compatibility: Maintain API compatibility

Development Setup

git clone https://github.com/kpirnie/kp-cache.git
cd kp-cache
composer install

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Packagist: kevinpirnie/kpt-cache

🙏 Acknowledgments

• Redis community for excellent documentation
• Memcached team for reliable caching
• PHP community for extensions and tools
• All contributors who helped improve this system

KPT Cache - Built with ❤️ for high-performance PHP applications