mreduar/laravel-balance
mreduar/laravel-balance adds balance and transaction tracking to Laravel Eloquent models. It provides a simple API for crediting and debiting accounts, recording balance history, and managing wallet-style ledgers for users, teams, or other models. Useful for credits, rewards, payments, and account b...
What this is: A lightweight, MIT-licensed Laravel package that attaches balance behaviour to any Eloquent model via a trait, exposes credit/debit/reset/set operations, and records each movement as a transaction row to form an audit trail. It is a convenience layer over a ledger, not a payments or accounting system.
Architecture fit: Good for Laravel-native applications that already treat Eloquent models as the domain boundary and want wallet, credits, loyalty points, or quota balances without designing a ledger from scratch. The trait-plus-transactions-table shape is the conventional Laravel pattern, so it should sit alongside existing models without imposing a new architectural paradigm. Its narrowness is the point: it does one thing, and it does not attempt to own pricing, billing, or reconciliation.
Integration feasibility: High for a greenfield feature in a single service. The surface area is small, so a spike is cheap and the integration risk is measurable within days. Two caveats cap this: the package is at 9 stars with a single maintainer and a last release dated 2023-10-10, so treat it as low-activity rather than actively maintained; and correctness under concurrent debits is the one property that cannot be assumed from a README and must be tested directly.
Technical risk: Low for lock-in, moderate for correctness, moderate for longevity. Lock-in is genuinely low because the package writes to our database in our models — the schema and data survive the package, so the exit is a refactor rather than a migration. Correctness is the real risk: balance arithmetic under concurrency, idempotency of retried operations, and whether a debit can drive a balance negative are all implementation details we must verify. Longevity is a bus-factor question: one maintainer, no evident release cadence, no visible security policy, and no evidence of a CI matrix testing the framework versions we actually deploy.
Key questions:
Stack fit: Evaluate as an ordinary Composer dependency in a Laravel service. Confirm the PHP and Laravel floors, the database engine (locking semantics differ across MySQL, Postgres, and SQLite), and whether the package assumes queues, caches, or config publishing. If we run multiple Laravel majors across services, verify each explicitly rather than trusting the single "latest" claim.
Migration path: For new adoption, install in a sandbox branch, publish and review any config and migrations, and inspect the generated schema before it reaches a shared environment. Critically, wrap the package behind an internal service or interface (for example WalletService->debit()) on day one. That one thin seam converts a dependency decision into a reversible one: if the package stalls or a concurrency defect surfaces, we swap the implementation without touching call sites. For existing balance data, backfill by writing an opening transaction per model rather than setting the balance directly, so the ledger remains the source of truth.
Compatibility: Check the package's composer.json constraints and changelog against our lockfile for transitive conflicts, and confirm v1.4.0 is genuinely additive rather than dropping older framework support. Run the package's own test suite, if any, against our pinned versions in CI — a passing upstream build on a version we do not deploy tells us nothing.
Sequencing:
Maintenance: We should plan on becoming the de facto maintainer if the upstream project goes quiet — but the cost is bounded precisely because the code is small and the data is ours. Budget a periodic review (dependency audit, framework-upgrade check) rather than continuous work, and set a re-evaluation date. A fork is a realistic fallback, not a crisis, which is what makes this a safe dependency to trial.
Support: Community-supported with no SLA and an unclear escalation path. Internal ownership of the wrapper interface is what protects us; nobody should be debugging product incidents by reading vendor source. Documentation of our usage pattern — not the package's — is the artifact that survives staff turnover.
Scaling: The transaction table is append-only and grows with activity, so index design, reporting queries, and long-term archival become our responsibility; balances are cheap to read, but ledger history is not. High-write balance types may need partitioning or a rollup. Confirm whether balance reads hit a stored column or aggregate the ledger, because that choice drives both performance and drift risk.
Failure modes to instrument: double-spend or overdraft under concurrent debits; drift between a stored balance and the sum of its transactions (reconcile on a schedule, not on trust); non-idempotent retries producing duplicate credits; partial writes leaving a transaction without a balance update or vice versa; and reporting reads that silently miss soft-deleted or archived rows. Any use touching real customer value should be reviewed by finance or compliance before launch, since "audit trail" here means a database table, not a controlled financial record.
Ramp-up: The API is small; an experienced Laravel engineer is productive in hours. The domain literacy takes longer — the team needs to internalise ledger thinking (movements, not mutable balances; compensating entries, not edits) and agree on invariants such as "balances never go negative" and "every balance change has exactly one transaction." That conceptual alignment, not the package, is the real onboarding cost and the thing most likely to cause a production incident if skipped.
How can I help you explore Laravel packages today?