Ganesha Laravel Package

Technical Evaluation

Architecture fit. Ganesha is a framework-agnostic implementation of the circuit breaker pattern with pluggable failure strategies (count-based, rate-based) and external state adapters (Redis, Memcached, MongoDB, Predis). That maps cleanly onto a Laravel application: the breaker belongs at the boundary of outbound I/O — HTTP calls to third-party APIs, queue jobs hitting flaky downstreams, and SOAP/gRPC clients — not inside domain logic. Because it is not Laravel-aware, it will not auto-register; we would own a thin service provider, config file, and facade/wrapper. That is a modest amount of glue in exchange for portability and a small, auditable API surface. The use of external state storage rather than in-process state is the right call for our topology and is compatible with Octane/Swoole and multi-node deployments.

Integration feasibility. composer require ackintosh/ganesha plus a storage adapter is a same-day spike. Production readiness is more about policy than code: deciding what counts as a failure (timeouts and 5xx yes, 4xx no), breaker granularity (per downstream service, per tenant, per endpoint), and fallback behavior when the circuit is open. Absent an official Laravel bridge, expect one to two sprints for wrapper, configuration, observability, shadow-mode calibration, and a game day. PHP and Laravel version compatibility should be verified against our runtime, but the framework-agnostic design makes Laravel-version coupling low.

Technical risk. The primary risk is the state store, not the library. If Redis is unavailable, breaker reads/writes fail, and we must explicitly choose fail-open (protect availability, risk cascading failure) or fail-closed (protect the downstream, degrade the user). That decision must be documented per dependency. Secondary risks: single-maintainer project (670 stars, low opportunity score of 4.91 — a utility, not a platform bet), half-open probe concurrency causing thundering herds, and misclassified errors opening circuits during normal client-error traffic. MIT license and a small API keep lock-in and exit costs low.

Key questions. Which dependencies get breakers first, and what is the blast radius of each being open? Where does shared state live, and what is the Redis SLA and latency budget? What is the fallback contract per dependency — cached response, degraded feature, or explicit 503? How do retries and breakers compose (breaker outside retry, or retry outside breaker)? How are state transitions emitted to logs/metrics/alerting? Do we accept single-maintainer risk, or budget for a vendored fork? What are the threshold, window, and cooldown values, and who owns them?

Integration Approach

Stack fit. PHP 8.x with Composer, Laravel 10–12, and Redis already in the platform make this a natural fit. The Redis or Predis adapter aligns with existing infrastructure; the alternative is a custom adapter over Laravel's cache contract, which adds work and hides breaker semantics — prefer the native adapter with a dedicated connection. Ganesha composes well with Guzzle middleware and Laravel's HTTP client, and can wrap queue job dispatch or consumption. It does not replace retries, timeouts, or bulkheads; it is one layer in a resilience stack, and the layering order must be explicit.

Migration path. There is no data migration — breaker state is ephemeral and rebuildable. The migration is behavioral. Sequence: (1) spike and architecture decision record covering failure classification and fallback policy; (2) service provider, namespaced config, and event/log hooks; (3) shadow mode on one non-critical dependency, recording would-be trips without enforcing; (4) enforce on one critical path with a defined fallback; (5) standardize a ResilientClient wrapper so teams do not hand-roll breakers; (6) expand dependency by dependency.

Compatibility. Framework-agnosticism means Laravel upgrades are unlikely to break us; PHP version constraints and the chosen Redis extension (ext-redis vs. Predis) are the real compatibility vectors. Under Octane, bind the breaker as a stateless singleton and never hold per-request state in it. Namespace breaker keys by environment, service, and tenant to avoid collisions between staging and production or across tenants. Pin with a caret constraint and a committed lock file, and run CI against the same Redis topology as production.

Sequencing. Calibrate thresholds in shadow mode before enforcing; otherwise the first real trip is also the first test. Roll out to the least-coupled dependency first so the fallback path is exercised with low customer impact. Defer multi-tenant granularity until the single-tenant model is proven, since per-tenant keys multiply Redis cardinality and evaluation cost.

Operational Impact

Maintenance. The library itself is small and stable, with a recent release (February 2025) and MIT licensing, so upgrade burden is low. The maintenance burden sits in our wrapper, threshold configuration, and the operational runbook. The meaningful risk is bus factor: one primary maintainer. Mitigate with version pinning, a documented fork contingency, and no deep coupling to internals. Treat this as a utility dependency, consistent with its 4.91 opportunity score, not a strategic platform commitment.

Support. No commercial support; reliance on GitHub issues and community. Internal ownership must be explicit — a named team owns the wrapper, thresholds, and on-call playbook. Supportability improves sharply if breaker state transitions emit structured events into existing observability, with dashboards for open/half-open counts and trip reasons.

Scaling. External state scales horizontally, but every guarded call adds a state-store round trip. At high RPS, Redis becomes a hot path: use a dedicated connection/pool, avoid per-request connection creation, and keep key cardinality bounded by choosing granularity deliberately (per dependency, not per endpoint, initially). Clock-based windows are sensitive to skew; ensure consistent time sources.

Failure modes. Redis outage preventing state reads/writes; thundering herd when a half-open circuit admits concurrent probes; false opens from misclassified 4xx responses or overly tight thresholds, amplifying an outage; key collisions across services or environments; state eviction causing flapping between open and closed; and retry/breaker misordering producing either no protection or double counting. Each needs an explicit, documented policy and an alert.

Ramp-up. Engineers familiar with resilience patterns need roughly half a day to be productive; the concepts, not the API, are the learning curve. Budget one to two sprints for full rollout including shadow calibration, dashboards, runbook, and a game day that deliberately trips a breaker in staging. The TPM ask is modest engineering time plus funded observability — not a platform migration.