Ha Bundle Laravel Package

Technical Evaluation

Architecture fit. The first thing a TPM has to flag is the framing: kibatic/ha-bundle is a Symfony bundle, not a Laravel package. It hooks into Symfony's DI container, bundle bootstrapping, and Doctrine DBAL's master/slave connection model. A Laravel application has none of those seams — Laravel uses Illuminate\Database over PDO, configures connections as arrays in config/database.php, and resolves them through DatabaseManager and connector classes. So the artifact does not fit our stack at all; what fits is the pattern it encodes: detect an unreachable write primary, stop retrying, fall back to a replica for reads, and surface a defined degraded mode instead of throwing connection errors on every request. Assessed as a dependency for a Laravel codebase, architecture fit is zero. Assessed as a reference implementation for a 300–600 line failover layer we write ourselves, it is moderately useful — it documents retry-and-give-up semantics that teams routinely get wrong on the first attempt.

Integration feasibility. Direct integration: not feasible without a rewrite of the bundle's bootstrapping and connection decoration, at which point we are no longer integrating it. The realistic Laravel path is: (1) use native read/write connection config for static read/write splitting, which we get for free; (2) if dynamic failover is genuinely required, implement a small failover-aware connector/connection subclass that wraps PDO, owns health-check state, and exposes a read-only degraded mode; (3) prefer pushing the whole problem to an infrastructure layer (ProxySQL, MySQL Router, RDS/Aurora Multi-AZ, Cloud SQL HA) that solves it once for every service we run. A TPM should treat any proposal to "port the bundle" as a build decision with build-level cost and ownership, not a dependency adoption.

Technical risk. High, on three independent axes. Provenance: 0 stars, 0 dependents, 0 downstream signal — the code has no evidence of production use, so we would be the first adopter of critical-path failover logic. Currency: bundles of this vintage typically pin to older Doctrine DBAL majors, and DBAL has since shipped native primary/replica configuration, meaning the wrapper is solving a problem the ORM now owns — adopting it risks fighting the framework during any future upgrade. Semantics: failover code fails in the expensive ways — routing writes to a lagging replica, split-brain during partial network partitions, connection storms on primary recovery, and "successful" failover that leaves the app degraded with no telemetry. None of these are covered by visible tests, and they are hard to detect outside a real incident rehearsal.

Key questions. What is the actual detection mechanism — TCP/SELECT 1 polling, exception-driven retry, or connect-timeout heuristics — and what is the retry budget before it declares failure? Does it fail closed or open: on primary loss, does it refuse writes outright, or silently send them to a replica? How does it handle replica lag, and does it distinguish "readable replica" from "replica caught up enough to trust"? Which engines and versions are supported, and does it understand the difference between MySQL's read_only flag and Postgres's read-only transaction semantics? What is the declared PHP/Symfony/DBAL matrix, and does it intersect with ours? Is this a fork of another project, and when was the last commit? Is there any test coverage of the failover path? What exactly does the MIT license require of us if we lift code into our own connector (retain the copyright and permission notice — cheap, but it must be done deliberately)?

Integration Approach

Stack fit. Poor as a package, workable as a blueprint. On Laravel we already have the static half of the problem solved by read/write keys per connection, which routes SELECTs to replicas and writes to the primary with no third-party code. The dynamic half — what happens when the primary disappears mid-incident — is where this bundle's ideas are relevant, and where our options are, in ascending order of risk: managed HA endpoint, proxy tier, in-house fallback connector, ported bundle. The TPM position should be that option four is never the right first choice.

Migration path. There is no upgrade or migration path from this repository into a Laravel application; the code would be reimplemented, not migrated. That reframing matters for planning: a "port" is a greenfield build with a reference document, sized as such. If a Symfony service exists elsewhere in the estate, the path there is a disposable spike against a real primary/replica pair, not a production rollout. For our Laravel services, the migration path to better availability runs through the platform roadmap: consolidate on a managed HA database or introduce a proxy, and delete the application-level concern entirely.

Compatibility. Assume incompatibility until proven. The gates are: Doctrine DBAL major (if we were on Symfony), Symfony version, PHP version, and — for any in-house port — our Laravel version's connection-manager internals, which change across majors. The behavioural compatibility question is more important than the version question: our MySQL and Postgres fleets have different failover characteristics, and a single PHP abstraction covering both tends to be correct for neither. Any port must be scoped to one engine first.

Sequencing.

1. Decision gate against the platform roadmap. If managed HA or a proxy tier lands within roughly two quarters, do nothing application-side and spend the effort on that migration — it solves the problem for every service, not one PHP app.
2. Confirm the requirement is real and app-level. Pull incident data: how many write-primary outages in the last 12 months, how long, what did users see, what did it cost. If the answer is "one 20-minute incident," the honest recommendation may be a runbook, not a connector.
3. Define the degradation policy with product before any code. Which surfaces stay up in read-only mode (browse, catalog, search, dashboards) and which fail with a clean error (checkout, signup, edits, uploads). This is a product decision the failover code merely enforces.
4. Only if 1–3 point to app-level work: time-boxed spike (2–3 engineer-weeks), one engine, non-production, with failover/failback/partial-failure scenarios scripted in advance.
5. Ship behind a flag, with observability wired before enablement — counters for failover events, current mode, replica lag observed at decision time — and a documented owner and expiry date on the accepted risk.

Build-vs-buy framing for the pitch. The bundle is MIT and tiny, which makes it look cheap. Price it as a fork: no upstream fixes, no CVE triage, and a permanent compatibility tax on every framework and DBAL upgrade. Two to three engineer-weeks to port the pattern competently, plus a small perpetual ownership cost on infrastructure-adjacent code most engineers will never open.

Operational Impact

Maintenance. We would own it outright, with no upstream to lean on. Every Laravel, PHP, or PDO upgrade becomes a review of critical-path failover code. The bundle's own maintenance risk is irrelevant because we would not be running it — but the pattern carries the same ongoing cost, and that cost should appear in the roadmap as a line item, not absorbed silently by whichever team builds it.

Support. No vendor, no community, no issue triage, no security patching. Incident support falls to the adopting team, and the knowledge concentrates in whoever ran the spike. For a component whose entire job is to work correctly during the worst hour of the year, that is the wrong knowledge profile. Mitigation: a written runbook, a named secondary owner, and a rehearsed failover game day before this is ever load-bearing.

Scaling. Application-level failover scales poorly in exactly the direction we are growing. Each PHP-FPM worker or container holds its own view of primary health, so during an outage N instances independently decide to reconnect, producing thundering-herd behaviour against the recovering primary and inconsistent routing decisions across the fleet. A proxy or managed endpoint makes one decision in one place and benefits every service. This is the single strongest argument for solving it below the application.

Failure modes. The ones that should worry a TPM, in descending severity: writes silently routed to a lagging replica (data integrity, and the kind of bug that surfaces weeks later as inconsistent records); split-brain during a network partition where two nodes each believe they are primary; recovery stampede that converts a 30-second blip into a 10-minute outage; in-flight transactions whose state is undefined after a mid-request failover; and "silent degradation" — the app is up, in read-only mode, nobody is paged, and conversion quietly drops for hours. Only the last is cheap to fix, and only with telemetry committed up front.

Ramp-up. Expect thin-to-nonexistent documentation; onboarding means reading the source to understand detection triggers and retry semantics. Budget for one deep owner, a runbook, and an explicit bus-factor acknowledgement. If the answer to "who can debug this at 3am in six months" is a single name, that is a finding, not a footnote.

Bottom line. As a TPM I would not approve this as a dependency on a Laravel stack — it is the wrong framework target and unproven even in its own ecosystem. The requirement it gestures at is real, but it belongs to the database platform, not to one application's connection layer. Recommend: close this package out as not adopted — wrong platform, unmaintained, unproven, run the decision gate against the managed-HA/proxy roadmap, and only fund the in-house fallback pattern if that roadmap sits more than two quarters out — with a recorded risk acceptance, an expiry date, and observability shipped before the flag is ever flipped.