create-circuit-breaker

Circuit Breaker Generator

Creates Circuit Breaker pattern infrastructure for resilience and fault tolerance.

When to Use

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

Naming Conventions

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

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