webrek/laravel-circuit-breaker

A circuit breaker for Laravel: stop hammering a failing dependency, fail fast, and recover automatically.

v1.0.0 2026-06-17 02:03 UTC

Requires

• php: ^8.2
• illuminate/cache: ^12.0 || ^13.0
• illuminate/console: ^12.0 || ^13.0
• illuminate/contracts: ^12.0 || ^13.0
• illuminate/support: ^12.0 || ^13.0

Requires (Dev)

• infection/infection: ^0.29
• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• mockery/mockery: ^1.6
• orchestra/testbench: ^10.0 || ^11.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0 || ^12.0

MIT

• Victor Hernandez

• http
• retry
• laravel
• fault-tolerance
• reliability
• laravel-package
• circuit-breaker
• resilience
• cascading-failure

README

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

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

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

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

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

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

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

The relay in 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

Lifecycle events let you alert on state changes:

Event	When
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

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

Component	Version
PHP	8.2+
Laravel	12.x / 13.x
Cache	A shared store (Redis) in production

Testing

composer install
composer test

Contributing

See CONTRIBUTING.md.

Security

Please review the security policy before reporting a vulnerability.

License

Released under the MIT license.