name: acc-create-circuit-breaker description: Generates Circuit Breaker pattern for PHP 8.5. Creates resilience component protecting against cascading failures with state management, fallback support, and metrics. Includes unit tests.

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