create-circuit-breaker

Circuit Breaker Generator

Creates Circuit Breaker pattern infrastructure for resilience and fault tolerance.

When to Use

Scenario	Example
External service calls	API integrations, payment gateways
Database connections	Prevent connection exhaustion
Cascading failures	Stop failure propagation
Service degradation	Graceful fallback when service unavailable

Component Characteristics

CircuitState Enum

• Closed: Normal operation, requests pass through
• Open: Failing, requests rejected immediately
• HalfOpen: Testing recovery, limited requests allowed

CircuitBreaker

• Wraps external service calls
• Tracks failures and successes
• Automatic state transitions
• Configurable thresholds and timeouts

CircuitBreakerConfig

• Failure threshold count
• Success threshold for recovery
• Open state timeout duration

---

Generation Process

Step 1: Generate Core Components

Path: src/Infrastructure/Resilience/CircuitBreaker/

1. CircuitState.php — Enum with state transitions
2. CircuitBreakerConfig.php — Configuration value object
3. CircuitBreakerException.php — Exception for open circuit

Step 2: Generate Circuit Breaker

Path: src/Infrastructure/Resilience/CircuitBreaker/

1. CircuitBreaker.php — Main implementation with state management

Step 3: Generate Factory and Registry

Path: src/Infrastructure/Resilience/CircuitBreaker/

1. CircuitBreakerFactory.php — Creates configured breakers
2. CircuitBreakerRegistry.php — Per-service breaker management

Step 4: Generate Tests

1. CircuitStateTest.php — State transition tests
2. CircuitBreakerTest.php — Breaker behavior tests

---

File Placement

Component	Path
All Classes	src/Infrastructure/Resilience/CircuitBreaker/
Unit Tests	tests/Unit/Infrastructure/Resilience/CircuitBreaker/

---

Naming Conventions

Component	Pattern	Example
State Enum	CircuitState	CircuitState
Config	CircuitBreakerConfig	CircuitBreakerConfig
Main Class	CircuitBreaker	CircuitBreaker
Factory	CircuitBreakerFactory	CircuitBreakerFactory
Registry	CircuitBreakerRegistry	CircuitBreakerRegistry
Exception	CircuitBreakerException	CircuitBreakerException
Test	{ClassName}Test	CircuitBreakerTest

---

Quick Template Reference

CircuitState

enum CircuitState: string
{
    case Closed = 'closed';
    case Open = 'open';
    case HalfOpen = 'half_open';

    public function allowsRequest(): bool;
    public function canTransitionTo(self $next): bool;
}

CircuitBreakerConfig

final readonly class CircuitBreakerConfig
{
    public function __construct(
        public int $failureThreshold = 5,
        public int $successThreshold = 3,
        public int $openTimeoutSeconds = 30,
        public int $halfOpenMaxAttempts = 3
    ) {}

    public static function default(): self;
    public static function aggressive(): self;
    public static function lenient(): self;
}

CircuitBreaker

final class CircuitBreaker
{
    public function execute(callable $operation, ?callable $fallback = null): mixed;
    public function canExecute(): bool;
    public function getState(): CircuitState;
    public function forceOpen(): void;
    public function forceClose(): void;
}

---

Usage Example

$breaker = $circuitBreakers->get('payment-gateway');

try {
    $result = $breaker->execute(
        operation: fn() => $paymentClient->charge($request),
        fallback: fn() => PaymentResult::deferred($request->id)
    );
} catch (CircuitBreakerException $e) {
    // Circuit is open
    return PaymentResult::serviceUnavailable($request->id);
}

---

State Transitions

CLOSED ─────failure threshold reached────→ OPEN
   ↑                                          │
   │                                          │ timeout elapsed
   │                                          ↓
success threshold reached              HALF-OPEN
   └────────────────────────────────────────┘
                        │
            failure in half-open
                        │
                        ↓
                      OPEN

---

Anti-patterns to Avoid

Anti-pattern	Problem	Solution
Global Circuit Breaker	One breaker for all services	Per-service breakers
No Fallback	Hard failure on open	Provide fallback strategy
Immediate Retry	Hammering failed service	Use timeout before HalfOpen
No Metrics	Can't monitor health	Log state transitions
Static Thresholds	Can't tune per service	Configurable per service
No Manual Override	Can't force open/close	Add force methods

---

References

For complete PHP templates and examples, see:

• references/templates.md — CircuitState, CircuitBreakerConfig, CircuitBreaker, Factory, Registry templates
• references/examples.md — HTTP client, payment gateway examples and tests