PHPackages                             algoyounes/circuit-breaker - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. algoyounes/circuit-breaker

ActiveLibrary[Utility & Helpers](/categories/utility)

algoyounes/circuit-breaker
==========================

Circuit Breaker is laravel package that provides a way to handle failures gracefully

v1.7(1mo ago)1626MITPHPPHP ^8.2CI passing

Since Jan 27Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/algoyounes/circuit-breaker)[ Packagist](https://packagist.org/packages/algoyounes/circuit-breaker)[ RSS](/packages/algoyounes-circuit-breaker/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (17)Used By (0)

[![Circuit Breaker Logo](assets/logo.png)](assets/logo.png)

[![Build Status](https://github.com/algoyounes/circuit-breaker/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/algoyounes/circuit-breaker/actions)[![Total Downloads](https://camo.githubusercontent.com/24abf597c3dbfe57f93978fa321d6e40dcca908891a004959247d282682d6461/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616c676f796f756e65732f636972637569742d627265616b6572)](https://packagist.org/packages/algoyounes/circuit-breaker)[![Latest Stable Version](https://camo.githubusercontent.com/8f868a6e1fa782e34e9374da866d2f0336055eb646181a1a7c53bd7026a58a45/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c676f796f756e65732f636972637569742d627265616b6572)](https://packagist.org/packages/algoyounes/circuit-breaker)[![License](https://camo.githubusercontent.com/44c07c67cc298a9202b6c8909ebc7092a8f326d780de6f5af2721cd25ea784e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616c676f796f756e65732f636972637569742d627265616b6572)](https://packagist.org/packages/algoyounes/circuit-breaker)

**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:

[![circuit-breaker.png](assets/circuit-breaker.png)](assets/circuit-breaker.png)

For more info, check the official pattern doc [here](https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker).

Prerequisites
-------------

[](#prerequisites)

This package requires:

- **PHP 8.2+**
- **Laravel 11+**
- **A configured Laravel cache driver**

Installation
------------

[](#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
-----

[](#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

[](#custom-callbacks)

You can define callbacks for key circuit states:

CallbackDescriptionParameters 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

[](#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

[](#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

[](#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
------------

[](#contributing)

Thank you for considering contributing to the Circuit Breaker package! Please check the [CONTRIBUTING](CONTRIBUTING.md) file for more details.

License
-------

[](#license)

The Circuit Breaker package is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance88

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 92.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Recently: every ~50 days

Total

16

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bfd15013ece7b7782813460af6ec7162ca0d9973cc0d9cf5ef3307f5afba0b5a?d=identicon)[Algo Younes](/maintainers/Algo%20Younes)

---

Top Contributors

[![algoyounes](https://avatars.githubusercontent.com/u/45436028?v=4)](https://github.com/algoyounes "algoyounes (65 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")

---

Tags

circuit-breakercircuit-breaker-patternlaravelresilienceresiliency-patternscircuit breakerlaravel-circuit-breakerphp-circuit-breaker

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/algoyounes-circuit-breaker/health.svg)

```
[![Health](https://phpackages.com/badges/algoyounes-circuit-breaker/health.svg)](https://phpackages.com/packages/algoyounes-circuit-breaker)
```

###  Alternatives

[illuminate/pipeline

The Illuminate Pipeline package.

9446.6M213](/packages/illuminate-pipeline)[illuminate/pagination

The Illuminate Pagination package.

10532.5M862](/packages/illuminate-pagination)[spatie/laravel-livewire-wizard

Build wizards using Livewire

4061.0M4](/packages/spatie-laravel-livewire-wizard)[illuminate/broadcasting

The Illuminate Broadcasting package.

7126.5M178](/packages/illuminate-broadcasting)[illuminate/redis

The Illuminate Redis package.

8314.0M314](/packages/illuminate-redis)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)