PHPackages webrek/laravel-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. [HTTP & Networking](/categories/http) 4. / 5. webrek/laravel-circuit-breaker ActiveLibrary[HTTP & Networking](/categories/http) webrek/laravel-circuit-breaker ============================== A circuit breaker for Laravel: stop hammering a failing dependency, fail fast, and recover automatically. v1.0.0(2d ago)00MITPHPPHP ^8.2CI passing Since Jun 17Pushed 2d agoCompare [ Source](https://github.com/webrek/laravel-circuit-breaker)[ Packagist](https://packagist.org/packages/webrek/laravel-circuit-breaker)[ Docs](https://github.com/webrek/laravel-circuit-breaker)[ RSS](/packages/webrek-laravel-circuit-breaker/feed)WikiDiscussions main Synced today READMEChangelogDependencies (11)Versions (2)Used By (0) Laravel Circuit Breaker ======================= [](#laravel-circuit-breaker) [![Latest Version on Packagist](https://camo.githubusercontent.com/9f5fb125e09b06572b37b31472eadf4d2a559074404b654ec6fb4b5c54170874/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77656272656b2f6c61726176656c2d636972637569742d627265616b65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/webrek/laravel-circuit-breaker)[![Total Downloads](https://camo.githubusercontent.com/3559694678c2902d8f1856b6f704c2b3a4ceb952cdd7bcd8ced473545c6da8b1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77656272656b2f6c61726176656c2d636972637569742d627265616b65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/webrek/laravel-circuit-breaker)[![Tests](https://camo.githubusercontent.com/72211a4ff9de7efe203222fb3d320c4ded38ab094ae0556d4aa00e2e8fa56265/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f77656272656b2f6c61726176656c2d636972637569742d627265616b65722f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/webrek/laravel-circuit-breaker/actions/workflows/tests.yml)[![PHP Version](https://camo.githubusercontent.com/66f01e4456b579acd78d7855aa459404392f27b8f000203049a3b72c0d9afad8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f77656272656b2f6c61726176656c2d636972637569742d627265616b65722e7376673f7374796c653d666c61742d737175617265)](https://php.net)[![License](https://camo.githubusercontent.com/6fe962f8c004998fab671360668f84e707dee4a2c19525fa19ab42be67be1740/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77656272656b2f6c61726176656c2d636972637569742d627265616b65722e7376673f7374796c653d666c61742d737175617265)](LICENSE) Stop a failing dependency from taking your app down with it. Wrap calls to an external service in a circuit breaker: after enough failures it **trips open**and fails fast — no more requests piling up on a dead endpoint — then probes for recovery and closes itself when the service is healthy again. Why --- [](#why) When a downstream service (a payment gateway, a partner API, a webhook endpoint) goes slow or down, every request to it sits there until it times out. Those requests pile up, exhaust your workers and connection pool, and **their outage becomes your outage** — a cascading failure. A circuit breaker watches the failures and, once they cross a threshold, short-circuits further calls for a cooldown so your app stays responsive while the dependency recovers. ``` use Webrek\CircuitBreaker\Facades\CircuitBreaker; $response = CircuitBreaker::for('payments')->call( fn () => Http::timeout(3)->post($url, $payload)->throw(), fallback: fn () => null, // returned while the circuit is open ); ``` Install ------- [](#install) ``` composer require webrek/laravel-circuit-breaker ``` Optionally publish the config: ``` php artisan vendor:publish --tag=circuit-breaker-config ``` State is stored in the cache. In production point it at a centralised store (Redis) so the breaker is shared across every process and server — the array and file drivers only protect a single process. How it works ------------ [](#how-it-works) A circuit moves between three states: - **Closed** — calls pass through. Each consecutive failure is counted; once it reaches `failure_threshold`, the circuit trips **open**. - **Open** — calls are short-circuited immediately (fallback or `CircuitOpenException`) without touching the dependency. After `cooldown_seconds`, the next call is allowed through as a trial: **half-open**. - **Half-open** — trial calls are let through. `success_threshold` successes in a row close the circuit; a single failure trips it back open. Usage ----- [](#usage) ### With a fallback [](#with-a-fallback) When a fallback is given, an open circuit (or a failing call) returns it instead of throwing. The fallback receives the `Throwable`: ``` $rate = CircuitBreaker::for('fx-api')->call( fn () => $this->fetchLiveRate(), fallback: fn (\Throwable $e) => $this->lastKnownRate(), ); ``` ### Without a fallback [](#without-a-fallback) Omit it and the breaker rethrows the underlying exception — or throws `CircuitOpenException` while open — so you can handle it yourself: ``` use Webrek\CircuitBreaker\Exceptions\CircuitOpenException; try { CircuitBreaker::for('payments')->call(fn () => $gateway->charge($order)); } catch (CircuitOpenException $e) { return back()->withErrors('Payments are temporarily unavailable.'); } ``` ### Not every exception is a failure [](#not-every-exception-is-a-failure) A `422` from a validation error means *your* request was wrong, not that the service is down — it should not trip the breaker. List such exceptions under `ignore` and they pass straight through without affecting the circuit: ``` // config/circuit-breaker.php 'defaults' => [ 'ignore' => [ Illuminate\Http\Client\RequestException::class, // only if you treat 4xx as caller error ], ], ``` ### Pairs with the outbox [](#pairs-with-the-outbox) The relay in [webrek/laravel-outbox](https://github.com/webrek/laravel-outbox)can deliver through a breaker so it stops retrying against an endpoint that is already down, and resumes automatically once it recovers. Observability and operations ---------------------------- [](#observability-and-operations) Lifecycle events let you alert on state changes: EventWhen`CircuitOpened`A circuit tripped open.`CircuitHalfOpened`An open circuit started a recovery trial.`CircuitClosed`A circuit recovered.Force a circuit closed by hand: ``` php artisan circuit-breaker:reset payments ``` Inspect state in code with `CircuitBreaker::for('payments')->state()` and `->available()`. Configuration ------------- [](#configuration) ``` return [ 'cache' => [ 'store' => env('CIRCUIT_BREAKER_CACHE'), // null = default; use Redis in production 'prefix' => 'circuit-breaker', 'ttl' => 86400, ], 'defaults' => [ 'failure_threshold' => 5, // consecutive failures that trip the circuit 'cooldown_seconds' => 30, // open → half-open after this 'success_threshold' => 1, // trial successes needed to close 'ignore' => [], // exceptions that do not count as failures ], 'circuits' => [ 'payments' => ['failure_threshold' => 3, 'cooldown_seconds' => 60], ], ]; ``` Requirements ------------ [](#requirements) ComponentVersionPHP8.2+Laravel12.x / 13.xCacheA shared store (Redis) in productionTesting ------- [](#testing) ``` composer install composer test ``` Contributing ------------ [](#contributing) See [CONTRIBUTING.md](CONTRIBUTING.md). Security -------- [](#security) Please review the [security policy](SECURITY.md) before reporting a vulnerability. License ------- [](#license) Released under the [MIT license](LICENSE). ### Health Score 39 — LowBetter than 85% of packages Maintenance99 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 Unknown Total 1 Last Release 2d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7d8deca81629993819087597b5ad7695976b02e3d014f038e26e985f35f569de?d=identicon)[webrek](/maintainers/webrek) --- Top Contributors [![webrek](https://avatars.githubusercontent.com/u/5001338?v=4)](https://github.com/webrek "webrek (1 commits)") --- Tags httplaravellaravel-packageretrycircuit breakerfault toleranceresiliencereliabilitycascading-failure ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/webrek-laravel-circuit-breaker/health.svg) ``` [![Health](https://phpackages.com/badges/webrek-laravel-circuit-breaker/health.svg)](https://phpackages.com/packages/webrek-laravel-circuit-breaker) ``` ### Alternatives [propaganistas/laravel-disposable-email Disposable email validator 6012.9M7](/packages/propaganistas-laravel-disposable-email)[laravel/ai The official AI SDK for Laravel. 9782.1M157](/packages/laravel-ai)[laravel/sail Docker files for running a basic Laravel application. 1.9k199.2M1.2k](/packages/laravel-sail)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 43140.3k](/packages/harris21-laravel-fuse)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 76518.2M115](/packages/laravel-mcp)[spatie/laravel-health Monitor the health of a Laravel application 87411.3M152](/packages/spatie-laravel-health) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)