Wallet Bundle Laravel Package

Technical Evaluation

Architecture fit: mismatch, and it is the defining fact. Despite being catalogued among PHP packages, mkurc1/wallet-bundle is explicitly a Symfony bundle, not a Laravel package. It offers no service provider, no publishable config, no Laravel migrations, and no Eloquent integration; it assumes Symfony's DI container, config/bundles.php registration, and Doctrine entity mapping. For a Laravel/PHP product this is not an install-and-configure decision — it is a port or a rebuild decision. Any plan that assumes composer require is a plan built on a false premise.

Integration feasibility: low as a runtime dependency, moderate as a reference implementation. The realistic options, in TPM terms:

1. Adopt as dependency — rejected. It would drag Symfony/Doctrine concerns into an Eloquent codebase and still require custom glue we would own and support.
2. Fork and port — feasible only because the surface area is small (wallet model, balance/transaction semantics, a service layer). Legally clean under MIT, but we inherit the design without its test coverage, and we own it permanently with no upstream.
3. Read, then build clean-room in Laravel — the default recommendation. Cost is measured in days, not weeks, and the result is idiomatic, reviewable, and ours.

Technical risk: high and concentrated in unverifiable areas. Seven stars, zero dependents, and a composite score of 0.155 give no evidence of production use anywhere. The repo is single-maintainer with no visible support model. This is money-adjacent code, which is the worst category for unvetted dependencies: failures are silent and financially material rather than loud and cosmetic. The package's own positioning — "lightweight," "decoupled from persistence" — reads as prototype-grade, not ledger-grade.

Key questions to resolve in a short source read (not a long evaluation):

• Is balance a mutable column, or derived from an append-only transaction ledger? A mutable column alone is a hard stop beyond demo use.
• Are writes wrapped in DB transactions with row locking (pessimistic lock or version column)? What isolation level is assumed?
• Is there an idempotency key on credit/debit, and an audit trail of who moved funds and why?
• Money representation: integer minor units or float/decimal? (Float is an immediate disqualifier.)
• Multi-currency support, or a single implicit currency?
• Supported PHP/Symfony versions and last commit date — if it targets EOL runtimes, stop the evaluation at the read.

Integration Approach

Stack fit: no overlap to exploit. Container, ORM, migration tooling, and eventing are all different. Every hour spent is net-new code; none of it is configuration. The honest framing for stakeholders is: we are buying a design reference, not a dependency.

Migration path. Time-box a spike of 1–2 engineer-days to read src/Entity/ (data shape), src/Resources/config/ and DependencyInjection/ (where balance mutation lives, what is configurable), and the Doctrine migrations (schema). Output is a one-page risk memo and an explicit build-vs-port decision. Then implement natively: wallets and wallet_entries tables, a HasWallet trait on User, and a WalletService that owns all mutations. Port the invariants — atomicity, locking, ledger shape — not the code. Preserve the MIT attribution if anything is copied.

Compatibility. Verify the composer.json PHP constraint against our runtime before the spike; an EOL target kills the option outright. Confirm license headers are intact across files, since we may vendor fragments. This check is minutes of work and prevents wasted days.

Sequencing.

1. Source read + risk memo (1–2 days).
2. Decision gate: clean-room build (default) vs. fork-port.
3. Data model: ledger-first, immutable transaction rows, balance derived or cached with reconciliation.
4. Service layer: atomic debit/credit, row locking, idempotency keys, domain events (WalletCredited/WalletDebited) for downstream listeners.
5. Test suite including concurrent-withdrawal and reconciliation cases.
6. Security/finance review gate before any real funds move.
7. Ops handoff: reconciliation job, drift alerting, dashboards.

Budget 3–6 engineer-weeks for a production-grade wallet regardless of path. This package compresses that by days, not weeks — which is the crux of the business case.

Leverage summary for a TPM: the package's value is as a scoping artifact. It confirms a basic wallet is a commodity capability, gives us a reference schema and a checklist of invariants, and lets us estimate the build with confidence. It does not justify a dependency.

Operational Impact

Maintenance. Adopting or forking means permanent ownership with no upstream to pull from — a single-maintainer repo with zero dependents is unlikely to absorb our patches. The build path carries identical ownership but yields code our team can review and reason about. Either way, budget ongoing ownership, not a dependency-update cadence.

Support. No vendor, no SLA, no community, no deprecation policy. The escalation path is one maintainer's GitHub issues — not an acceptable support model for financial functionality. Internal documentation and a named domain owner are mandatory regardless of path.

Scaling. Wallet workloads are write-contended: one balance row per user becomes a hot row under concurrent debits. Expect to need row-level locking, short transactions, and eventually an event-sourced ledger with asynchronous balance projection. Nothing in a bundle this size suggests those concerns are addressed, so assume we design them.

Failure modes to instrument for:

• Double-spend from missing or incorrect locking under concurrency.
• Partial writes — debit commits, credit fails, no cross-record atomicity.
• Duplicate submissions absent idempotency keys (retries, double-clicks, webhook replays).
• Rounding/precision drift if amounts are floats rather than integer minor units.
• Silent ledger/balance divergence — needs a scheduled reconciliation job and alerting on nonzero drift.
• Schema drift where the bundle's User assumptions conflict with our users table.

Ramp-up. The codebase is small enough for one engineer to absorb in a day — a genuine upside. The risk is not complexity; it is that the package delivers less than its description implies. The larger cost is domain literacy: whoever owns this needs ledger-design judgment, not just Laravel fluency. Plan a finance-aware reviewer at the design gate, and treat "looks simple" as the signal to look harder.