🚀 Laravel SmartFailover

The Ultimate Laravel Package for Bulletproof Service Failover

Never let a service failure bring down your application again

📖 Documentation • 🚀 Quick Start • 💡 Examples • 🏥 Health Monitoring • 🤝 Contributing

</div>

📋 Table of Contents

🎯 Why SmartFailover?
✨ Features
🚀 Quick Start
⚙️ Configuration
💡 Usage Examples
🏥 Health Monitoring
🔔 Notifications & Alerts
📊 Dashboard Integration
🧪 Testing
📈 Performance
🔒 Security
🤝 Contributing
📄 License

🎯 Why SmartFailover?

The Problem 😰

graph TD
    A[Your Laravel App] --> B[Single Database]
    A --> C[Single Cache]
    A --> D[Single Queue]
    
    B --> E[💥 Database Fails]
    C --> F[💥 Cache Fails]
    D --> G[💥 Queue Fails]
    
    E --> H[🔴 App Crashes]
    F --> H
    G --> H
    
    style H fill:#ff6b6b
    style E fill:#ff6b6b
    style F fill:#ff6b6b
    style G fill:#ff6b6b

The Solution 🎉

graph TD
    A[Your Laravel App] --> B[SmartFailover]
    
    B --> C[Primary DB]
    B --> D[Backup DB]
    B --> E[Primary Cache]
    B --> F[Backup Cache]
    B --> G[Primary Queue]
    B --> H[Backup Queue]
    
    C --> I[💥 Fails]
    I --> J[✅ Auto Switch to Backup]
    
    E --> K[💥 Fails]
    K --> L[✅ Auto Switch to Backup]
    
    G --> M[💥 Fails]
    M --> N[✅ Auto Switch to Backup]
    
    J --> O[🟢 App Stays Online]
    L --> O
    N --> O
    
    style O fill:#51cf66
    style J fill:#51cf66
    style L fill:#51cf66
    style N fill:#51cf66

</div>

SmartFailover transforms your single-point-of-failure Laravel application into a resilient, self-healing system that automatically switches to backup services when primary ones fail.

🎯 Key Benefits

| Before SmartFailover | After SmartFailover | |---------------------|-------------------| | 💥 Single database failure = App down | ✅ Automatic failover to backup database | | 🐌 Manual intervention required | 🚀 Zero-downtime automatic switching | | 😰 No visibility into service health | 📊 Real-time health monitoring | | 🔥 Panic when services fail | 😌 Sleep peacefully with alerts |

✨ Features

🛡️ Bulletproof Service Protection

</div>

| Service | Primary | Fallbacks | Health Checks | |---------|---------|-----------|---------------| | 🗄️ Database | MySQL, PostgreSQL | Multiple backups | ✅ Connection tests | | 🚀 Cache | Redis, Memcached | Array, File | ✅ Read/Write tests | | 📬 Queue | SQS, Redis | Database, Sync | ✅ Job dispatch tests | | 📧 Mail | SMTP, SES | Mailgun, Log | ✅ Connection tests | | 💾 Storage | S3, GCS | Local, FTP | ✅ File operations |

🎯 Smart Features

</div>

🚀 Quick Start

📦 Installation

# 1️⃣ Install the package
composer require mirzaaghazadeh/smart-failover

# 2️⃣ Publish configuration
php artisan vendor:publish --provider="Mirzaaghazadeh\SmartFailover\SmartFailoverServiceProvider" --tag="config"

# 3️⃣ Configure your services (optional)
php artisan vendor:publish --provider="Mirzaaghazadeh\SmartFailover\SmartFailoverServiceProvider" --tag="migrations"

⚡ 30-Second Setup

// That's it! Start using SmartFailover immediately:

use Mirzaaghazadeh\SmartFailover\Facades\SmartFailover;

// Wrap your existing code with failover protection
SmartFailover::db('mysql', ['mysql_backup'])
    ->cache('redis', ['memcached'])
    ->execute(function() {
        // Your existing Laravel code works unchanged!
        $user = User::create($userData);
        Cache::put('user_' . $user->id, $user, 3600);
        return $user;
    });

🎉 That's it! Your app is now bulletproof!

</div>

⚙️ Configuration

🔧 Basic Configuration

The config/smart-failover.php file is your control center:

<?php

return [
    // 🗄️ Database Failover
    'database' => [
        'primary' => 'mysql',
        'fallbacks' => ['mysql_backup', 'sqlite_fallback'],
        'health_check_interval' => 30, // seconds
        'retry_attempts' => 3,
        'retry_delay' => 1000, // milliseconds
    ],
    
    // 🚀 Cache Failover  
    'cache' => [
        'primary' => 'redis',
        'fallbacks' => ['memcached', 'array'],
        'health_check_interval' => 15,
        'retry_attempts' => 2,
    ],
    
    // 📬 Queue Failover
    'queue' => [
        'primary' => 'sqs',
        'fallbacks' => ['redis', 'database'],
        'health_check_interval' => 60,
        'retry_attempts' => 3,
    ],
    
    // 🔔 Notifications
    'notifications' => [
        'slack' => [
            'webhook_url' => env('SMART_FAILOVER_SLACK_WEBHOOK'),
            'channel' => '#alerts',
        ],
        'telegram' => [
            'bot_token' => env('SMART_FAILOVER_TELEGRAM_BOT_TOKEN'),
            'chat_id' => env('SMART_FAILOVER_TELEGRAM_CHAT_ID'),
        ],
    ],
];

🌍 Environment Variables

Add these to your .env file:

# Slack Notifications
SMART_FAILOVER_SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

# Telegram Notifications  
SMART_FAILOVER_TELEGRAM_BOT_TOKEN=your_bot_token
SMART_FAILOVER_TELEGRAM_CHAT_ID=your_chat_id

# Health Check Settings
SMART_FAILOVER_HEALTH_ENABLED=true
SMART_FAILOVER_HEALTH_CACHE_TTL=60

💡 Usage Examples

🎯 The Magic One-Liner

use Mirzaaghazadeh\SmartFailover\Facades\SmartFailover;

// Protect ALL your services in one beautiful line
SmartFailover::db('mysql', ['mysql_backup'])
    ->cache('redis', ['memcached', 'array'])
    ->queue('sqs', ['redis', 'database'])
    ->execute(function() {
        // Your normal Laravel code - unchanged!
        $order = Order::create($orderData);
        Cache::put('order_' . $order->id, $order, 3600);
        ProcessOrderJob::dispatch($order);
        return $order;
    });

🗄️ Database Failover Examples

<details> <summary><strong>🔍 Click to see Database Examples</strong></summary>

// ✅ Simple Database Failover
SmartFailover::db('mysql_primary', ['mysql_backup'])
    ->execute(function() {
        return User::where('active', true)->get();
    });

// ✅ With Graceful Degradation
SmartFailover::db('mysql_primary', ['mysql_backup'])
    ->gracefulDegradation(function() {
        // Return cached data when all databases fail
        return Cache::get('users_fallback', collect());
    })
    ->execute(function() {
        return User::all();
    });

// ✅ Advanced Retry Logic
SmartFailover::db('mysql_primary', ['mysql_backup'])
    ->retryAttempts(5)
    ->retryDelay(2000) // 2 seconds
    ->retryMultiplier(1.5) // Exponential backoff
    ->execute(function() {
        return User::with('orders')->paginate(50);
    });

</details>

🚀 Cache Failover Examples

<details> <summary><strong>🔍 Click to see Cache Examples</strong></summary>

// ✅ Multi-Level Cache Failover
SmartFailover::cache('redis', ['memcached', 'array'])
    ->execute(function() {
        Cache::put('user_preferences', $preferences, 3600);
        return Cache::get('user_preferences');
    });

// ✅ Direct Cache Manager Usage
use Mirzaaghazadeh\SmartFailover\Services\CacheFailoverManager;

$cacheManager = app(CacheFailoverManager::class);
$cacheManager->setStores('redis', ['memcached']);

// Store with automatic failover
$cacheManager->put('user_123', $userData, 3600);

// Retrieve with automatic failover
$userData = $cacheManager->get('user_123');

// ✅ Cache with Fallback Data
SmartFailover::cache('redis', ['memcached'])
    ->gracefulDegradation(function() {
        return [
            'user_preferences' => config('app.default_preferences'),
            'settings' => config('app.default_settings'),
        ];
    })
    ->execute(function() {
        return [
            'user_preferences' => Cache::get('user_prefs'),
            'settings' => Cache::get('app_settings'),
        ];
    });

</details>

📬 Queue Failover Examples

<details> <summary><strong>🔍 Click to see Queue Examples</strong></summary>

// ✅ Queue Failover
SmartFailover::queue('sqs', ['redis', 'database'])
    ->execute(function() {
        ProcessOrderJob::dispatch($order);
        SendEmailJob::dispatch($user, $em

SmartFailover

Install / Use

README

🚀 Laravel SmartFailover

📋 Table of Contents

🎯 Why SmartFailover?

The Problem 😰

The Solution 🎉

🎯 Key Benefits

✨ Features

🛡️ Bulletproof Service Protection

🎯 Smart Features

🚀 Quick Start

📦 Installation

⚡ 30-Second Setup

🎉 That's it! Your app is now bulletproof!

⚙️ Configuration

🔧 Basic Configuration

🌍 Environment Variables

💡 Usage Examples

🎯 The Magic One-Liner

🗄️ Database Failover Examples

🚀 Cache Failover Examples

📬 Queue Failover Examples