Circuit Breaker Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Alignment: The bundle is tightly integrated with Symfony’s ecosystem, leveraging HttpClient, Cache, and EventDispatcher components. This makes it a natural fit for Laravel applications using Laravel Symfony Bridge (e.g., symfony/http-client, symfony/cache, symfony/event-dispatcher).
• Circuit Breaker Pattern: The decorator pattern for HttpClient aligns well with Laravel’s service container and HTTP client abstractions (e.g., GuzzleHttp, Symfony HttpClient).
• PSR-6 Cache Backend: Laravel’s built-in Cache facade (PSR-6 compliant via illuminate/cache) can serve as the storage backend, reducing external dependencies.

Integration Feasibility

• High: The bundle’s core functionality (circuit breaker logic) is language-agnostic (PHP + PSR standards). The main challenge is Symfony-specific integrations (e.g., HttpClient, EventDispatcher), which can be mapped to Laravel equivalents:
  • Replace symfony/http-client with Laravel’s HttpClient facade (or Guzzle).
  • Use Laravel’s Cache facade (PSR-6) instead of Symfony’s CachePool.
  • Replace EventDispatcher with Laravel’s Events system (via symfony/event-dispatcher or native Event facade).
• Dependency Risk: The bundle depends on gabrielanhaia/php-circuit-breaker, which is stable but niche. Laravel’s ecosystem lacks a native circuit breaker, so this fills a gap.

Technical Risk

Key Questions

1. Does the bundle support Laravel’s HttpClient facade (Symfony HttpClient wrapper)?
   • If not, will a custom decorator be needed to bridge Laravel’s Http client?
2. How will circuit breaker state (PSR-6 cache) be shared across Laravel’s cache drivers?
   • Ensure the chosen driver (Redis, database) supports atomic operations for state updates.
3. What exceptions should trigger circuit breaker trips?
   • Laravel’s HttpClient throws ConnectException, RequestException, etc.—map these to the bundle’s config.
4. How will Symfony events (e.g., CircuitBreakerStateChanged) be handled in Laravel?
   • Use Laravel’s Events system or a listener adapter for Symfony events.
5. What’s the fallback for failed requests when the circuit is open?
   • Define a retry strategy (e.g., exponential backoff) or graceful degradation (e.g., cached responses).

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Dependency Setup

   • Install required packages:

     composer require bizkit/circuit-breaker-bundle gabrielanhaia/php-circuit-breaker symfony/http-client symfony/cache symfony/event-dispatcher
     

   • For Laravel, skip the bundle and manually integrate the core library (php-circuit-breaker) with Laravel’s HttpClient.

2. Phase 2: Configuration

   • Define circuit breaker rules in config/circuit_breaker.php:

     return [
         'clients' => [
             'main' => [
                 'threshold' => 5,          // Failures before tripping
                 'timeout' => 30,           // Open state duration (seconds)
                 'half_open_timeout' => 10, // Half-open state duration
                 'exceptions' => [
                     \Symfony\Contracts\HttpClient\Exception\ClientException::class,
                     \Symfony\Contracts\HttpClient\Exception\ServerException::class,
                 ],
             ],
             'scoped' => [
                 // Per-client configs
             ],
         ],
         'cache' => env('CACHE_DRIVER', 'redis'), // PSR-6 cache driver
     ];
     

3. Phase 3: HttpClient Decorator

   • Create a service provider to decorate Laravel’s HttpClient:

     use GabrielAnhia\CircuitBreaker\CircuitBreaker;
     use GabrielAnhia\CircuitBreaker\CircuitBreakerFactory;
     use Illuminate\Support\Facades\Http;
     use Symfony\Component\HttpClient\NativeHttpClient;
     
     public function register()
     {
         $cache = Cache::store(config('circuit_breaker.cache'));
         $factory = new CircuitBreakerFactory($cache);
     
         $httpClient = new NativeHttpClient();
         $decoratedClient = $factory->create($httpClient, config('circuit_breaker.clients.main'));
     
         Http::macro('withCircuitBreaker', function () use ($decoratedClient) {
             return new HttpClient($decoratedClient);
         });
     }
     

4. Phase 4: Event Handling (Optional)

   • Subscribe to circuit breaker events:

     use GabrielAnhia\CircuitBreaker\Event\CircuitBreakerStateChanged;
     
     Event::listen(CircuitBreakerStateChanged::class, function ($event) {
         Log::info("Circuit breaker state changed: {$event->getState()}");
     });
     

Compatibility

• Laravel 9/10: Fully compatible if using Symfony HttpClient (illuminate/http-client).
• GuzzleHttp: Requires additional adapter layer to wrap Guzzle responses/exceptions.
• Cache Drivers: Supports all PSR-6 drivers (Redis, Memcached, database, file).
• Event System: Works with Laravel’s Events or Symfony’s EventDispatcher.

Sequencing

1. Start with a single high-risk endpoint (e.g., payment gateway).
2. Monitor circuit breaker state in logs/metrics.
3. Gradually expand to other external APIs.
4. Optimize thresholds based on failure rates.

Operational Impact

Maintenance

• Pros:
  • Centralized configuration (single config/circuit_breaker.php file).
  • PSR-6 cache reduces state management complexity.
  • Symfony event integration enables observability (logs, metrics).
• Cons:
  • New dependency (php-circuit-breaker) requires monitoring.
  • Cache invalidation: Manual cleanup may be needed if circuit breaker state persists indefinitely.
  • Symfony-specific code may need updates if Laravel’s HttpClient changes.

Support

• Debugging:
  • Use telescope or laravel-debugbar to inspect circuit breaker state.
  • Log CircuitBreakerStateChanged events for observability.
• Common Issues:
  • False positives: Misconfigured exception lists may trip circuits unnecessarily.
  • Cache staleness: Ensure cache driver is healthy (e.g., Redis connectivity).
• Rollback Plan:
  • Disable circuit breaker for specific clients via config:

    'clients' => [
        'problematic_api' => ['enabled' => false],
    ]
    

Scaling

• Horizontal Scaling:
  • Circuit breaker state is shared via cache (Redis/Memcached), so all instances see