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(1mo ago)058MITPHPPHP ^8.2CI passing Since Jun 17Pushed 4w 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 2w ago 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 dragging your app down with it. Wrap calls to an external service in a *circuit breaker*: after enough failures it **trips open**and fails fast — so requests stop piling up on a downed endpoint — then probes for recovery and closes itself once the service is healthy again. Why --- [](#why) When a downstream service (a payment gateway, a partner API, a webhook endpoint) gets slow or goes down, every request to it hangs until it times out. Those requests pile up, exhaust your workers and connection pool, and **their outage becomes yours**: a cascading failure. A circuit breaker watches for failures and, once they cross a threshold, cuts off subsequent calls during a cooldown so your app keeps responding 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 ); ``` Installation ------------ [](#installation) ``` 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 centralized 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 cut off immediately (*fallback* or `CircuitOpenException`) without touching the dependency. After `cooldown_seconds`, the next call is allowed as a trial: **half-open**. - **Half-open** — trial calls are let through. `success_threshold` consecutive successes close the circuit; a single failure trips it open again. Usage ----- [](#usage) ### With a fallback [](#with-a-fallback) When a fallback is provided, 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 — for you to handle 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 shouldn't open the breaker. List those exceptions under `ignore` and they pass through without affecting the circuit: ``` // config/circuit-breaker.php 'defaults' => [ 'ignore' => [ Illuminate\Http\Client\RequestException::class, // only if you treat 4xx as a 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 already-downed endpoint, and resumes automatically once it recovers. Observability & operations ------------------------------ [](#observability--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 open the circuit 'cooldown_seconds' => 30, // open → half-open after this 'success_threshold' => 1, // trial successes needed to close 'ignore' => [], // exceptions that don't 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 41 — FairBetter than 87% of packages Maintenance92 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 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 47d 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 (2 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 6023.2M7](/packages/propaganistas-laravel-disposable-email)[laravel/ai The official AI SDK for Laravel. 1.1k4.6M275](/packages/laravel-ai)[laravel/sail Docker files for running a basic Laravel application. 1.9k212.4M1.4k](/packages/laravel-sail)[iazaran/smart-cache Smart Cache is a caching optimization package designed to enhance the way your Laravel application handles data caching. It intelligently manages large data sets by compressing, chunking, or applying other optimization strategies to keep your application performant and efficient. 21114.2k](/packages/iazaran-smart-cache)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 78727.1M205](/packages/laravel-mcp)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 24773.9k](/packages/harris21-laravel-fuse) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)