PHPackages                             pixelfederation/circuit-breaker-bundle - 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. pixelfederation/circuit-breaker-bundle

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

pixelfederation/circuit-breaker-bundle
======================================

An analogous bundle to Java's Hystrix in PHP world.

5.0.2(3mo ago)1226.5k↓31%BSD-3-ClausePHPPHP >=8.4CI passing

Since Sep 9Pushed 3mo ago4 watchersCompare

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

READMEChangelog (10)Dependencies (23)Versions (15)Used By (0)

Circuit breaker bundle
======================

[](#circuit-breaker-bundle)

This bundle tries to copy the famous java [Hystrix](https://github.com/Netflix/Hystrix) library and tries to make the usage of the circuit breaking pattern effortless to the developers.

The developers can just mark any service as circuit broken, using special annotations and this bundle makes all the wiring under the hood automatically.

The current backend implementation is using [Ganesha](https://github.com/ackintosh/ganesha).

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

[](#installation)

```
$ composer require pixelfederation/circuit-breaker-bundle
```

Configuration
-------------

[](#configuration)

Just enable the bundle. There are no configuration options for now.

```
// in config/bundles.php add this line:
PixelFederation\CircuitBreakerBundle\Bridge\Symfony\PixelFederationCircuitBreakerBundle::class
```

Usage
-----

[](#usage)

To activate circuit breaking on a given service, the service has to implement the `PixelFederation\CircuitBreakerBundle\CircuitBrokenService` interface.

The class mustn't be marked as `final`, because a proxy class is derived from it under the hood.

To configure circuit breaking, you can use the class level configuration or method level configuration. The class level configuration is valid for all the circuit-broken methods. It is configured as a class level annotation `@CircuitBreakerService`. To mark a public method as circuit broken, the `@CircuitBreaker` annotation or attribute has to be used:

```
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreakerService;
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreaker;

/**
 * @CircuitBreakerService(
 *    defaultFallback="makeDefaultFallbackRequest",
 *    ignoreExceptions={BadMethodCallException::class}
 * )
 */
class Service {
    /**
     * @CircuitBreaker()
     */
    public function iShouldBeCircuitBroken(): int
    {
        return 0;
    }
}
```

or

```
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreakerService;
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreaker;

#[CircuitBreakerService(defaultFallback: 'makeDefaultFallbackRequest', ignoreExceptions: [BadMethodCallException::class])]
class Service {
    #[CircuitBreaker()]
    public function iShouldBeCircuitBroken(): int
    {
        return 0;
    }
}
```

The configuration options for the `@CircuitBreakerService` are:

- **defaultFallback**: a public method of the same class which should be called on an exception occurrence, if no fallback is configured for a circuit-broken method.
- **ignoreExceptions**: exception list, which doesn't trigger marking the wrapped service as failing

The method level annotation `@CircuitBreaker` can override the class level configuration with its own configuration options, which are:

- **fallbackMethod**: a public method of the same class which should be called on an exception occurrence
- **ignoreExceptions**: exception list, which doesn't trigger marking the wrapped service as failing

```
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreaker;

class Service {
    /**
     * @CircuitBreaker(fallbackMethod="makeSpecialFallbackRequest")
     */
    public function iShouldBeCircuitBroken(): int
    {
        return 0;
    }
}
```

or

```
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreaker;

class Service {
    #[CircuitBreaker(fallbackMethod: 'makeSpecialFallbackRequest')]
    public function iShouldBeCircuitBroken(): int
    {
        return 0;
    }
}
```

The **fallback methods have to be public** as well.

**IMPORTANT:** Fallback methods have to have the same method signature as the fallbackable methods, because fallback methods are being called with the same arguments.

**IMPORTANT:** Doctrine annotations support will be dropped in the future, so it is recommended to use the bundle attributes instead.

**NOTICE REGARDING COMPLEX SCENARIOS:** It is also possible to define fallback methods for fallback methods in some more complex scenarios. An example of such scenario might be, when there is an API call in the default/fallbackable method. It's fallback method might have a different call to a different API, which means, that such method could use a fallback as well. In that case it can have configured a fallback method which tries to load data from some cache. Such a method might also use a fallback method which might return some default value.

Full example
------------

[](#full-example)

```
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreaker;
use PixelFederation\CircuitBreakerBundle\Annotation\CircuitBreakerService;
use PixelFederation\CircuitBreakerBundle\CircuitBrokenService;
use BadMethodCallException;
use InvalidArgumentException;
use RuntimeException;

/**
 * The class level annotation activates circuit breaking configuration on methods
 * marked with the @CircuitBreaker annotation.
 * In this case, also the default fallback for each circuit broken method is configured
 * (the 'makeDefaultFallbackRequest' method)
 *
 * The ignoreExceptions option sets exceptions, on which occurrence the service won't be marked
 * as failing, e.g. some app/system level exceptions, which don't need to have to do anything
 * with http requests under the hood.
 *
 * @CircuitBreakerService(
 *    defaultFallback="makeDefaultFallbackRequest",
 *    ignoreExceptions={BadMethodCallException::class}
 * )
 */
class TestService implements CircuitBrokenService
{
    private SomeHttpClient $client;

    public function __construct(SomeHttpClient $client)
    {
        $this->client = $client;
    }

    /**
     * This method is marked to be circuit-broken. It uses the class level configured fallback
     * and ignores the class level configured exceptions.
     *
     * @CircuitBreaker()
     */
    public function makeRequest(): int
    {
        return $this->client->makeRequest(); // it is important to set http timeouts here
    }

    /**
     * This method is marked to be circuit-broken. It uses a different fallback, not the one
     * configured on class level.
     *
     * @CircuitBreaker(fallbackMethod="makeSpecialFallbackRequest")
     */
    public function makeRequestWithCustomCircuitBreaker(string $param): int
    {
        return $this->client->makeAnotherRequest($param); // it is important to set http timeouts here
    }

    public function makeDefaultFallbackRequest(): void
    {
        return 1; // ideally there is no call to any external dependency in the fallback method
    }

    // notice that this fallback method has the same method signature as the method makeRequestWithCustomCircuitBreaker
    public function makeSpecialFallbackRequest(string $param): void
    {
        return 0; // ideally there is no call to any external dependency in the fallback method
    }
}
```

Enjoy ;)

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance81

Actively maintained with recent releases

Popularity34

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~134 days

Recently: every ~107 days

Total

13

Last Release

99d ago

Major Versions

1.2.2 → 2.0.02023-07-10

2.0.1 → 3.0.02024-12-05

3.0.0 → 4.0.02025-11-04

4.0.0 → 5.0.02026-02-03

PHP version history (6 changes)1.0.0PHP >=7.4

1.0.1PHP ^7.4

2.0.0PHP >=8.1

3.0.0PHP >=8.2

4.0.0PHP >=8.3

5.0.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/2f41a9b6b3fcc495a546791e3993b29832b7a4b08f34ad094a1131e2e8784d01?d=identicon)[pixelfederation](/maintainers/pixelfederation)

---

Top Contributors

[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (309 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (304 commits)")[![dzoudzou](https://avatars.githubusercontent.com/u/2709249?v=4)](https://github.com/dzoudzou "dzoudzou (6 commits)")[![pmysiak](https://avatars.githubusercontent.com/u/1159674?v=4)](https://github.com/pmysiak "pmysiak (2 commits)")[![MatokUK](https://avatars.githubusercontent.com/u/5272678?v=4)](https://github.com/MatokUK "MatokUK (1 commits)")

---

Tags

circuit-breakerganeshaphpsymfony-bundle

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[simplesamlphp/simplesamlphp

A PHP implementation of a SAML 2.0 service provider and identity provider.

1.1k12.4M193](/packages/simplesamlphp-simplesamlphp)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)

PHPackages © 2026

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