alex97lewis/laravel-circuit-breaker

A simple, drop-in circuit breaker implementation for Laravel applications with Redis caching and Artisan commands

v1.0.0 2025-07-15 19:47 UTC

Requires

• php: ^8.1
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/redis: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0 || ^11.0 || ^12.0

MIT

• Alex97Lewis

• redis
• laravel
• fault-tolerance
• reliability
• circuit-breaker
• resilience

README

A simple, elegant circuit breaker implementation for Laravel applications with Redis caching and comprehensive Artisan command support.

Features

• 🔄 Three States: Closed, Open, Half-Open with automatic transitions
• ⚡ Redis-Powered: Fast, reliable caching with Laravel's Redis integration
• 🎛️ Configurable: Failure thresholds, recovery timeouts, and more
• 📝 Auto-Logging: Comprehensive failure logging with context
• 🛠️ Artisan Commands: Test, monitor, and manage circuit breakers via CLI
• 🔍 Dynamic Discovery: No hardcoded circuit breaker names
• 🎨 Laravel Integration: Facades, helpers, and service container ready
• 📦 Zero Dependencies: Uses only Laravel's built-in components

Installation

Install via Composer:

composer require alex97lewis/laravel-circuit-breaker

The package will automatically register itself via Laravel's package discovery.

Publish Configuration (Optional)

php artisan vendor:publish --tag=circuit-breaker-config

Usage

Basic Usage

use Alex97Lewis\CircuitBreaker\CircuitBreaker;

$circuitBreaker = new CircuitBreaker('api-service');

try {
    $result = $circuitBreaker->call(function() {
        // Your risky operation here
        return Http::get('https://external-api.com/data');
    });
} catch (CircuitBreakerOpenException $e) {
    // Circuit is open, handle gracefully
    return $fallbackData;
}

Using Helper Functions

// Simple helper
$result = with_circuit_breaker(function() {
    return Http::get('https://external-api.com/data');
}, 'api-service');

// Get circuit breaker instance
$cb = circuit_breaker('database-service', [
    'failure_threshold' => 3,
    'recovery_timeout' => 30
]);

Using Facade

use Alex97Lewis\CircuitBreaker\CircuitBreakerFacade as CircuitBreaker;

$result = CircuitBreaker::call(function() {
    return SomeService::riskyOperation();
});

// Check state
if (CircuitBreaker::isAvailable()) {
    // Safe to proceed
}

Configuration

Environment variables:

• CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 - Failures before opening
• CIRCUIT_BREAKER_RECOVERY_TIMEOUT=60 - Seconds before retry
• CIRCUIT_BREAKER_TIMEOUT=30 - Operation timeout
• CIRCUIT_BREAKER_LOG_FAILURES=true - Log failures

States

• Closed: Normal operation
• Open: Failing fast, rejecting calls
• Half-Open: Testing if service recovered

Features

• ✅ Zero dependencies (uses Laravel Cache)
• ✅ Named circuit breakers for different services
• ✅ Configurable thresholds and timeouts
• ✅ Automatic logging
• ✅ Helper functions and facade
• ✅ Drop-in modular design
• ✅ Built-in Artisan commands for testing and management

Artisan Commands

The module includes several Artisan commands for testing and managing circuit breakers:

Test Circuit Breaker

php artisan circuit-breaker:test [name] [--threshold=2] [--timeout=1]

Test a circuit breaker with simulated failures.

Check Status

php artisan circuit-breaker:status [name]

Show the status of a specific circuit breaker or all circuit breakers.

Reset Circuit Breaker

php artisan circuit-breaker:reset {name} [--all]

Reset a circuit breaker to closed state or reset all circuit breakers.