Laravel
In a Laravel application the package is a service provider, a config file, a Fuse facade, and a fuse() helper. You do not register the provider yourself. Composer discovery loads Milon\Fuse\Laravel\FuseServiceProvider and aliases the facade as Fuse.
composer require milon/fuse
php artisan vendor:publish --tag=fuse-config
Publishing is optional. Without it, the package config is still merged, and the defaults from Configuration apply.
Resolve a fuse
use Milon\Fuse\CircuitOpenException;
use Milon\Fuse\Laravel\Facades\Fuse;
try {
$invoice = Fuse::for('billing-sdk')->run(fn () => $this->billing->charge($amount));
} catch (CircuitOpenException $exception) {
return response('Billing unavailable', 503)
->header('Retry-After', (string) ($exception->retryAfterSeconds ?? 0));
}
fuse('billing-sdk') is the same as Fuse::for('billing-sdk'):
fuse('billing-sdk')->run(fn () => $this->billing->charge($amount));
fuse()->configFor('billing-sdk')->failureThreshold;
fuse()->store(); // the shared CircuitBreakerStore
for() reads the shared config, then overlays config('fuse.breakers.billing-sdk') when that entry is an array. The store is the singleton bound by the provider, so every for('billing-sdk') in every request shares one circuit.
$fuse = Fuse::for(
name: 'billing',
operation: 'charge',
app: 'punt',
);
That key is fuse:punt:billing:charge when key_prefix is fuse.
The facade class is Milon\Fuse\Laravel\Facades\Fuse. That is not the core Milon\Fuse\Fuse value object — import the facade (or use the Fuse alias / fuse() helper) in Laravel code.
Named breakers
Keep strict numbers on the dependency that cannot afford a long outage, and leave everyone else on the defaults:
return [
'store' => env('FUSE_STORE', 'cache'),
'cache_store' => env('FUSE_CACHE_STORE'),
'key_prefix' => env('FUSE_KEY_PREFIX', 'fuse'),
'failure_threshold' => 8,
'failure_window_seconds' => 60,
'open_seconds' => 30,
'half_open_probes' => 2,
'counted_http_statuses' => [502, 503, 504],
'count_timeouts' => true,
'count_connection_errors' => true,
'count_http_500' => false,
'breakers' => [
'billing-sdk' => [
'failure_threshold' => 3,
'open_seconds' => 15,
],
],
];
Read the merged config without building a fuse:
Fuse::configFor('billing-sdk')->failureThreshold; // 3
Fuse::configFor('search')->failureThreshold; // 8
Fuse::configFor()->openSeconds; // 30
Cache store
FUSE_STORE=cache is the default. The provider resolves Illuminate\Contracts\Cache\Repository. Set FUSE_CACHE_STORE=redis to pin a store from config/cache.php. Leave FUSE_CACHE_STORE empty to use the default cache.
An open circuit stored in Redis is visible to the next PHP request and to every server that uses that Redis.
Container bindings
| Binding | What you get |
|---|---|
Milon\Fuse\Contracts\CircuitBreakerStore |
LaravelCacheStore or DatabaseStore |
Milon\Fuse\Contracts\CircuitEventDispatcher |
Dispatches into Laravel's event system |
Milon\Fuse\Laravel\FuseManager |
Extends FuseFactory; also the Fuse facade root |
Each Fuse::for() / fuse('…') returns a new fuse bound to the shared store and the config for that name. Under the hood that is the same FuseFactory API documented in Plain PHP.
State-change events
The provider wires Fuse into Laravel's event system. Listen for CircuitOpened, CircuitHalfOpened, or CircuitClosed:
use Illuminate\Support\Facades\Event;
use Milon\Fuse\Events\CircuitOpened;
Event::listen(CircuitOpened::class, function (CircuitOpened $event): void {
logger()->warning('Circuit opened', [
'key' => $event->storageKey,
'reason' => $event->reason,
]);
});
Saloon connectors that use HasCircuitBreaker share the same dispatcher. Event classes, reasons, and plain-PHP / PSR-14 setup are in Events.
Artisan commands
Inspect and reset circuits from the console:
php artisan fuse:status
php artisan fuse:status billing
php artisan fuse:status billing --operation=charge --app=punt
php artisan fuse:reset billing --operation=charge
php artisan fuse:reset billing --force
Example status output fields: name, operation, app, storage key, state, failure count, opened_at, half-open counters, and whether a snapshot is stored.
fuse:status without a name lists every entry under config('fuse.breakers'). Pass a name to inspect any circuit, including ones that are not in that list. fuse:reset deletes the stored snapshot (same as breaker()->reset()); use --force to skip the confirmation prompt.
When discovery is off
Add the provider to bootstrap/providers.php (Laravel 11+) or config/app.php:
Milon\Fuse\Laravel\FuseServiceProvider::class,
An unknown store name
FUSE_STORE=redis does not select the Redis cache. store is only cache or database. Redis is selected with FUSE_STORE=cache and FUSE_CACHE_STORE=redis. Any other store value throws RuntimeException: Fuse store [redis] is not supported.