Download the PHP package farzai/breaker without Composer

Circuit Breaker - PHP

A production-ready PHP Circuit Breaker implementation for building resilient applications with PSR-14 compliant event system, type-safe event objects, and comprehensive monitoring capabilities.

Features

• Circuit Breaker Pattern - Protect your application from cascading failures
• Auto-managed Instances - Service registry with automatic instance management
• PSR-14 Event System - Type-safe, immutable event objects with priority support
• Event Subscribers - Organize event listeners with subscriber pattern
• Built-in Monitoring - LoggingSubscriber and MetricsSubscriber included
• Performance Tracking - Execution time metrics for all operations
• Exception-Safe - Event listeners won't break your circuit breaker
• Advanced Storage - File, Memory, PSR-16 (Redis/Memcached), with decorators and fallback chains
• Flexible Configuration - Customizable thresholds and timeouts

Installation

Requirements

• PHP 8.2 or higher
• psr/event-dispatcher ^1.0 (automatically installed)
• psr/log ^3.0 for logging features (automatically installed)
• psr/simple-cache ^3.0 for PSR-16 cache integration (automatically installed)

Basic Usage

The easiest way to get started is using the Breaker facade, which provides a clean, Laravel-inspired API:

Why use the Breaker facade?

• ✅ One-liner API - No manual setup required
• ✅ Auto-managed instances - Circuit breakers created and cached automatically
• ✅ Zero boilerplate - Just protect your calls and go
• ✅ Clean, familiar syntax - Laravel-style API that feels natural

Configuring Services

Health Monitoring

Dependency Injection (Recommended for Production)

For production applications, use dependency injection for better testability:

💡 Tip: The facade (Breaker::protect()) is perfect for quick scripts and simple use cases. For production services, inject BreakerManager for better testability.

See examples/dependency_injection.php for complete examples.

Event Listeners

Monitor circuit breaker events to track failures, state changes, and performance:

Event Priority

Control the execution order of listeners using priorities (higher = earlier):

Event Propagation Control

Stop event propagation to prevent subsequent listeners from executing:

Event Subscribers

For better organization, group related event listeners into subscriber classes:

Built-in Subscribers

The library provides ready-to-use subscribers:

LoggingSubscriber

Automatically logs all circuit breaker events using PSR-3 logger:

MetricsSubscriber

Automatically collects metrics for all events:

Storage Architecture

The circuit breaker features a modern, pattern-based storage layer with multiple design patterns for flexibility and scalability.

Quick Start

By default, circuit state is stored in memory. For production, use persistent file storage:

Available Storage Adapters

File Storage

Persistent filesystem storage with atomic writes:

In-Memory Storage

Fast, non-persistent storage for testing or short-lived processes:

PSR-16 Cache Adapter

Use any PSR-16 cache implementation (Redis, Memcached, etc.):

Advanced Storage Patterns

With Decorators (Logging, Metrics, Retry)

High Availability with Fallback Chain

Storage Features

✅ SHA-256 Key Hashing - Prevents service key collisions ✅ Atomic Writes - Prevents data corruption ✅ File Locking - Thread-safe concurrent access ✅ Automatic Cleanup - Orphaned temp file detection ✅ PSR-16 Support - Redis, Memcached, any cache ✅ Decorator Pattern - Composable logging, metrics, retry ✅ Fallback Chain - High availability ✅ TTL Support - Automatic expiration

Circuit Breaker States

The circuit breaker operates in three states:

1. CLOSED: All requests pass through to the service. This is the default state when everything is working normally.
2. OPEN: Requests fail fast without calling the service. This happens after the failure threshold is reached, protecting your system from cascading failures.
3. HALF-OPEN: After the timeout period, the circuit allows a limited number of test requests to check if the service has recovered.

Best Practices

Service Isolation

Configure different services with appropriate thresholds:

Appropriate Thresholds

Configure thresholds based on service characteristics:

Always Use Fallbacks

Always provide fallbacks for critical operations:

Monitoring Circuit Health

Use event subscribers for comprehensive monitoring:

Circuit Breaker Pattern Integration

Integrate circuit breakers within your application architecture using dependency injection:

Event System Features

PSR-14 Compliance

The event system is fully PSR-14 compliant, making it compatible with standard PHP event dispatching tools and libraries. All event objects and the event dispatching mechanism follow the PSR-14 standard for event dispatcher interfaces.

Available Event Types

All events extend AbstractCircuitEvent and provide:

All events provide common methods:

• getCircuitBreaker() - Get the circuit breaker instance
• getServiceKey() - Get the service identifier
• getCurrentState() - Get current circuit state
• getTimestamp() - Get event timestamp
• stopPropagation() - Stop event from reaching other listeners
• isPropagationStopped() - Check if propagation was stopped

Exception-Safe Dispatching

Event listeners are exception-safe - if a listener throws an exception, it won't break the circuit breaker:

Execution Metrics

Track performance with built-in execution time tracking:

Immutable Event Objects

All event objects are immutable - their state cannot be changed after creation, ensuring data consistency:

Manual Usage (Advanced)

For advanced use cases where you need fine-grained control, you can manually instantiate CircuitBreaker instances:

When to use manual instantiation:

• You need custom time providers for testing
• You require specific logger or repository instances per breaker
• You're building a library that wraps the circuit breaker
• You need to pass the breaker instance to multiple collaborators

For most use cases, we recommend using the Breaker facade or BreakerManager instead.

License

This project is licensed under the MIT License - see the LICENSE file for details.