README

A framework-agnostic circuit breaker implementation that prevents cascading failures by monitoring error rates and temporarily blocking requests when thresholds are exceeded.

Installation

You can install the package via composer:

composer require christopheraseidl/circuit-breaker

Laravel Installation

The package auto-registers its service provider and automatically wires up Laravel's cache, logger, and mailer as adapters.

You may optionally publish the configuration file:

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

After publishing, update the config file to use Laravel's env() helper (recommended):

'notifiers' => [
    'email' => [
        'recipients' => [env('MAIL_FROM_ADDRESS')],
        'from_address' => env('MAIL_FROM_ADDRESS'),
        'from_name' => env('MAIL_FROM_NAME'),
    ],
],

Optionally publish the email notification view:

php artisan vendor:publish --tag="circuit-breaker-views"

Usage

Basic Example

use christopheraseidl\CircuitBreaker\CircuitBreaker;

// Create circuit breaker instance
$breaker = new CircuitBreaker(
    name: 'payment-gateway',
    cache: $cache,        // Must implement CacheContract
    logger: $logger,      // Must implement LoggerContract  
    notifier: $notifier,  // Must implement NotifierContract
    config: [
        'failure_threshold' => 5,
        'window_seconds' => 60,
        'recovery_timeout_seconds' => 300,
    ]
);

// Wrap external service calls
if ($breaker->canAttempt()) {
    try {
        $result = $paymentGateway->charge($amount);
        $breaker->recordSuccess();
        return $result;
    } catch (\Exception $e) {
        $breaker->recordFailure();
        throw $e;
    }
} else {
    throw new ServiceUnavailableException('Payment service temporarily unavailable');
}

Laravel Example

use christopheraseidl\CircuitBreaker\CircuitBreakerFactory;

// Using dependency injection
public function __construct(
    private CircuitBreakerFactory $circuitBreakerFactory
) {}

public function processPayment($amount)
{
    $breaker = $this->circuitBreakerFactory->make('payment-service', [
        'failure_threshold' => 3,
        'recovery_timeout_seconds' => 120,
    ]);
    
    if ($breaker->canAttempt()) {
        try {
            $response = Http::timeout(5)->post('https://payments.example.com/charge', [
                'amount' => $amount,
            ]);
            $breaker->recordSuccess();
            return $response->json();
        } catch (\Exception $e) {
            $breaker->recordFailure();
            return ['error' => 'Payment service temporarily unavailable'];
        }
    }
    
    return ['error' => 'Payment service is currently down'];
}

// Or resolve from container
$factory = app(CircuitBreakerFactory::class);
$breaker = $factory->make('api-service');

if (! $breaker->canAttempt()) {
    return cache()->remember('api-fallback-data', 3600, fn() => [...]);
}

Monitoring Circuit State

// Check circuit state
if ($breaker->isOpen()) {
    // Circuit is open - requests are blocked
}

if ($breaker->isHalfOpen()) {
    // Circuit is testing recovery
}

// Get statistics
$stats = $breaker->getStats();
// [
//     'name' => 'payment-gateway',
//     'state' => 'open',
//     'failure_count' => 5,
//     'failure_threshold' => 5,
//     'recovery_timeout_seconds' => 300,
// ]

// Manually reset circuit
$breaker->reset();

Configuration

The default configuration covers common use cases:

[
    'defaults' => [
        'failure_threshold' => 5,          // Open circuit after 5 failures
        'window_seconds' => 60,            // Count failures within 60 seconds
        'recovery_timeout_seconds' => 300, // Try recovery after 5 minutes
        'half_open_max_attempts' => 3,     // Allow 3 tests before reopening
        'half_open_delay' => 1,            // Base delay, in seconds, between recovery attempts
    ],
    'notifiers' => [
        'email' => [
            'recipients' => null,      // Set email addresses for notifications
            'from_address' => null,    // Set sender email address
            'from_name' => 'Circuit Breaker',
        ],
    ],
]

Implementing Adapters

To use the circuit breaker outside Laravel, implement the required contracts:

use christopheraseidl\CircuitBreaker\Contracts\CacheContract;

class RedisCache implements CacheContract
{
    public function put(string $key, mixed $value, ?int $ttl = 1): bool
    {
        return $this->redis->setex($key, $ttl, serialize($value));
    }
    
    public function get(string $key, mixed $default = null): mixed
    {
        $value = $this->redis->get($key);
        return $value !== false ? unserialize($value) : $default;
    }
    
    // ... implement remaining methods
}

Testing

./vendor/bin/pest

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Chris Seidl
• All Contributors

License

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