README

Circuit Breaker is a Laravel package that provides a simple and efficient way to manage service calls and prevent cascading failures. It lets you define custom callbacks for key circuit states and run operations with circuit breaker logic.

The following diagram illustrates how the Circuit Breaker Pattern works:

For more info, check the official pattern doc here.

Prerequisites

This package requires:

PHP 8.2+
Laravel 11+
A configured Laravel cache driver

Installation

You can install the package via Composer:

composer require algoyounes/circuit-breaker

You can publish the configuration file using the following command:

php artisan vendor:publish --provider="AlgoYounes\CircuitBreaker\Providers\CircuitBreakerServiceProvider" --tag="config"

Usage

You can manage specific services with granular control using the forService(...) method. the service-name parameter is a unique identifier key for your service, ensuring its circuit breaker configuration is isolated from other services.

$circuit = $this->circuitManager->forService('service-name');

Tip

Use the unique service-name key across your application to consistently reference the same circuit configuration (e.g., 'payment-service', ...)

Custom Callbacks

You can define callbacks for key circuit states:

Callback	Description	Parameters Received
`onOpen`	Triggered when the circuit goes into OPEN, blocking calls to prevent further failures	`CircuitTransition`
`onHalfOpen`	The circuit enters HALF-OPEN to test stability, letting a few requests through	`CircuitTransition`
`onClose`	The circuit returns to CLOSED, allowing all requests without restrictions	`CircuitTransition`
`onSuccess`	Fires when a request succeeds, indicating system availability	`CircuitResult`, `CircuitTransition`
`onFailure`	Triggered when a request fails, potentially opening the circuit	`CircuitResult`, `CircuitTransition`
`onSteadyState`	Indicates the circuit is stable, with no need for changes	`CircuitTransition`

Example of defining callbacks:

$circuit->onOpen(function (CircuitTransition $circuitTransition) { 
    // Your custom logic here
});

$circuit->onSuccess(function (CircuitResult $circuitResult, CircuitTransition $circuitTransition) {
    // Your custom logic here
});

// Params passed are optional

Running an Operation

To run an operation and manage its state through the circuit breaker, use the run method:

$circuit->run(function () {
    // Your service call here
});
// or
$circuit->run($this->serviceName->create(...));

This will execute the provided closure, applying the circuit breaker logic (e.g., open, half-open, closed states) around the service call.

Note

If you prefer a more direct approach, you can create a CircuitBuilder instance:

$circuit = CircuitBuilder::make('service-name')

Simplified Operation

For a simplified approach, use the run method directly from CircuitManager:

$this->circuitManager->run('service-name', function () {
    // Your service call here
});
// or
$this->circuitManager->run('service-name', $this->serviceName->create(...));

Guzzle Middleware Integration

The package provides a Guzzle middleware to automatically manage circuit breaker logic for HTTP requests.

To enable the middleware, add the following to your Guzzle client configuration:

use AlgoYounes\CircuitBreaker\Middleware\GuzzleMiddleware;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

$stack = HandlerStack::create();
$stack->push(GuzzleMiddleware::create());

$client = new Client([
    'handler' => $stack,
]);

$response = $client->get('https://api.example.com', [
    'headers' => [
        'X-Circuit-Key' => 'service-name',
    ],
]);

Contributing

Thank you for considering contributing to the Circuit Breaker package! Please check the CONTRIBUTING file for more details.

License

The Circuit Breaker package is open-sourced software licensed under the MIT license.

algoyounes / circuit-breaker

Maintainers

Package info

Statistics

Security