Laravel Wallet Uuid Laravel Package

Product Decisions This Supports

• Wallet/ledger feature feasibility. This package is a thin adapter that lets bavix/laravel-wallet key wallets by UUID instead of auto-increment integers. It is only relevant if you are (or plan to be) building balances, credits/debits, payouts, or stored-value ledgers on top of laravel-wallet.
• Identifier strategy / API contract decisions. Whether wallet IDs exposed in your API, URLs, webhooks, and partner integrations are sequential integers (enumerable, leaky) or UUIDs (opaque, safe for external exposure). This is a security-adjacent product decision, not just a technical one.
• Multi-tenant and distributed-write roadmaps. UUID wallet keys help if you plan to create wallets from multiple services, queue workers, or pre-generate IDs client-side before persistence.
• Build vs. buy. The alternative is (a) fork/patch laravel-wallet's migrations and models yourself, or (b) adopt a different ledger product. This package exists because laravel-wallet's UUID support is not first-class; it is a small, single-maintainer glue layer — weigh that against the cost of owning the schema change yourself.
• Roadmap gating for a Laravel upgrade. Release 4.0.0 exists primarily to align with laravel-wallet v12. This effectively ties your wallet stack's upgrade path to laravel-wallet's release cadence and, transitively, to the Laravel/PHP versions v12 requires.

When to Consider This Package

Consider it when all of the following hold:

• You have already chosen bavix/laravel-wallet as your ledger engine and are on a version line compatible with this release (v12 for 4.x).
• You have a concrete requirement for non-sequential wallet identifiers: public-facing wallet IDs, partner/API exposure, multi-tenant isolation, or ID generation ahead of insert.
• You are comfortable with a very small, single-maintainer dependency whose surface area is essentially a model trait plus migrations. The blast radius is low, which is the main mitigating factor.
• You are on a Laravel/PHP version that laravel-wallet 12 supports. Note that 4.0.0's own changes are compatibility and tooling: the only functional line is "add support laravel-wallet 12"; PHPUnit ^11 and the GitHub Actions bumps are dev/CI-only and impose nothing on your runtime.

Look elsewhere (or hand-roll the change) when:

• You are not using laravel-wallet. There is no standalone value here.
• You are pinned to laravel-wallet ≤ 11 or an older Laravel. This is a major release with a raised compatibility floor — treat 4.0.0 as breaking on the dependency graph, not as a feature upgrade. Stay on 3.0.x until your Laravel/laravel-wallet upgrade lands, and do not let a routine composer update pull this across the boundary.
• You need first-class UUID support with vendor SLAs, or your audit/compliance requirements demand a maintained ledger with documented migration and support guarantees.
• Your only motivation is "UUIDs are best practice." Sequential internal IDs are fine for internal-only wallets; adopting this adds a dependency and a schema decision for no user-visible benefit.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a small open-source add-on for our wallet/ledger stack. It lets wallet identifiers be UUIDs rather than sequential numbers, so wallet IDs are safe to expose in APIs and links and cannot be enumerated by an attacker. The newly published 4.0.0 is a maintenance release: it aligns the package with the current version of our ledger library and modernizes its test tooling. There are no new product capabilities here and no cost — the decision it supports is about identifier strategy and keeping our upgrade path unblocked, not about new features.

For engineering (the honest version):

• Scope: a model trait + migration overrides on top of laravel-wallet. Tiny, readable, low lock-in — we can vendor or reimplement it in an afternoon if it is abandoned.
• 4.0.0 is a major bump driven by compatibility: adds laravel-wallet 12 support; raises the dev-only PHPUnit floor to ^11; the remainder is Dependabot CI noise. Expect it to drop support for older laravel-wallet/Laravel lines even though the changelog does not spell that out — verify composer.json constraints before merging.
• Action: pin explicitly (^3.0 or ^4.0), upgrade laravel-wallet and this package together in a dedicated PR, and re-run wallet migration/backfill tests. Do not treat it as a background patch update.
• Risk: single maintainer, low release cadence, no security surface (no network, no auth logic). The real risk is version-lag against laravel-wallet, not code quality — budget a small, recurring maintenance allowance rather than assuming it tracks upstream automatically.