README

PHP Circuit Breaker

A robust, production-ready implementation of the Circuit Breaker pattern for PHP. Protect your microservices from cascading failures with configurable thresholds, multiple storage backends, an event system, and manual override capabilities.

How It Works

stateDiagram-v2
    [*] --> Closed
    Closed --> Open : Failures ≥ threshold
    Open --> HalfOpen : Timeout expires
    HalfOpen --> Closed : Successes ≥ threshold
    HalfOpen --> Open : Any failure

Installation

composer require gabrielanhaia/php-circuit-breaker:^3.0

Optional Dependencies

Install only what you need:

# For Redis storage
# Requires ext-redis PHP extension

# For PSR-16 (SimpleCache) storage
composer require psr/simple-cache

# For PSR-6 (Cache) storage
composer require psr/cache

# For PSR-14 event dispatcher bridge
composer require psr/event-dispatcher

Quick Start

use GabrielAnhaia\PhpCircuitBreaker\CircuitBreaker;
use GabrielAnhaia\PhpCircuitBreaker\CircuitBreakerConfig;
use GabrielAnhaia\PhpCircuitBreaker\Storage\InMemoryStorage;

$storage = new InMemoryStorage();
$config  = new CircuitBreakerConfig(
    failureThreshold: 5,
    openTimeout:      30,
);

$cb = new CircuitBreaker($storage, $config);

$service = 'payment-api';

if (!$cb->canPass($service)) {
    // Circuit is open — use fallback
    return cachedResponse();
}

try {
    $result = callPaymentApi();
    $cb->recordSuccess($service);
    return $result;
} catch (\Throwable $e) {
    $cb->recordFailure($service);
    return cachedResponse();
}

Features

• Multiple storage backends — InMemory, Redis, APCu, Memcached, PSR-6, PSR-16
• Success threshold — require N consecutive successes before closing a half-open circuit
• Event system — react to state changes with listeners; optional PSR-14 bridge
• Manual override — force circuits open/closed for maintenance windows or testing
• State inspection — query effective circuit state at any time
• Immutable config — type-safe CircuitBreakerConfig value object
• Zero required extensions — only ext-redis, ext-apcu, ext-memcached needed if you use those adapters
• PHPStan level max — fully statically analyzed
• PHP 8.1+ — uses native enums, readonly properties, and named arguments

Documentation

Upgrading from v2

See UPGRADE-3.0.md for a detailed migration guide.

Key Breaking Changes

Deprecated Methods (Removed in v4)

• $cb->failed($service) → use $cb->recordFailure($service)
• $cb->succeed($service) → use $cb->recordSuccess($service)

Development

# Install dependencies
composer install

# Run tests
composer test                              # All tests
vendor/bin/phpunit --testsuite Unit        # Unit tests only
vendor/bin/phpunit --testsuite Integration # Integration tests only

# Static analysis
composer phpstan

# Code style
composer cs-check    # Check for violations
composer cs-fix      # Auto-fix violations

CI

GitHub Actions runs on PHP 8.1, 8.2, 8.3, 8.4 with three jobs:

• Tests — unit + integration (with Redis service)
• Static Analysis — PHPStan level max
• Code Style — PHP-CS-Fixer (PER-CS + PHP 8.1 migration)

Support

If this library helps you, consider buying me a coffee:

License

MIT — see LICENSE for details.

Created by Gabriel Anhaia | Buy Me a Coffee