- What is harris21/laravel-fuse and what problem does it solve?
- Laravel Fuse is a circuit breaker that sits on the queue path rather than the HTTP path. Job middleware gates whether a job may run, while a cache-backed state machine tracks per-service health and opens the circuit when a downstream dependency is degraded. This stops a queue full of retries from hammering a flaky third party and prevents duplicated side effects. It is aimed at teams whose workers call payments, KYC, shipping, email, or partner APIs where $tries and backoff alone are too blunt.
- How do I install and configure laravel-fuse?
- Install it with Composer, publish the config file, and optionally publish the Blade view for the status page. Register the middleware on the jobs or job base class that call the services you want protected, then define per-service thresholds and register the transition listeners. There are no migrations and no daemon to run, so a first protected service typically takes days rather than weeks.
- Does laravel-fuse work with Laravel Horizon and multiple queues?
- Yes. The package is deliberately thin, consisting of middleware, a config file, a cache namespace, and a Blade view, so it composes with Horizon, dispatchSync, and multi-queue topologies. Because state is stored in the cache rather than a database table, each worker reads the same shared health state. Just make sure all workers use the same cache store and namespace.
- How does the laravel-fuse circuit breaker state machine work?
- Middleware checks whether a job is allowed to run, and a cache-backed state machine tracks health per service. Probes such as OldestJobProbe decide when an open circuit is allowed to close again, and transition listeners plus the /fuse status page expose the current state. A successful probe closes the circuit even if the counter write fails, which avoids long recovery penalties.
- Does laravel-fuse require database migrations or extra infrastructure?
- No. There are no database migrations, no service provider gymnastics beyond registration, and no long-running daemon. The trade-off is that all circuit state lives in the cache, which means the cache becomes part of the critical path for job dispatch correctness. Use a reliable shared cache store and monitor it accordingly.
- How does laravel-fuse handle dotted service names like payments.stripe?
- Before v0.11.0, dotted service names fell through to global defaults with no warning, so any dotted naming convention was silently unconfigured in production. Version 0.11.0 makes config resolution predictable so names like payments.stripe pick up their own thresholds. If you use dots in service names, upgrade before rolling out to production.
- What changed in v0.11.0 and is upgrading safe?
- v0.11.0 fixes silent misconfiguration around dotted service names, removed hard-coded default thresholds, and added peak windows that can cross midnight, plus isolation for custom cache prefixes. It also contains reporter and listener exceptions and stops cache failures from converting a successful job into a failed one that calls the external service twice. Audit any custom recovery strategy that throws deliberately, since that pattern now releases the job instead of hard-stopping it, except on the sync driver.
- Does laravel-fuse behave differently on the sync queue driver or with dispatchSync?
- Yes, there is a deliberate driver asymmetry. On async drivers, gating errors and recovery strategies release the job back onto the queue, but on sync and dispatchSync the error is still thrown. Any behavior assertions in your tests, or synchronous internal callers, should be exercised on both paths. This matters most if you rely on the circuit breaker to hard-stop work.
- How do I secure the /fuse status page in production?
- The status page is a normal route, so gate it behind your existing auth or admin middleware rather than leaving it open. When status_page.enabled is off combined with custom middleware, the routes return 404, which is the intended behavior. Note that /fuse/data returns 503 during cache outages, so dashboards should treat that as a signal rather than a broken endpoint.
- What should I monitor in production when running laravel-fuse?
- Watch queue age and not just failure counts, because a persistently broken cache now causes jobs to be released with their delay instead of counting toward $maxExceptions. That produces a long release loop rather than a clean dead-letter, so age-based alerts catch it faster. Also watch circuit state transitions and cache availability, since state lives in the cache. Services relying on the old implicit 60-at-peak threshold will now trip at default_threshold at all hours, so circuits may open earlier than historical baselines.