Laravel Wallet Uuid Laravel Package

Getting Started

This release (4.0.0) is a compatibility drop for laravel-wallet v12; there are no new end-user features. Start there.

1. Confirm your stack can take both majors together:

   composer require bavix/laravel-wallet:^12.0 bavix/laravel-wallet-uuid:^4.0
   

   If composer refuses, run composer why-not bavix/laravel-wallet ^12.0 — the uuid package's constraint is the usual culprit.
2. Publish the config and migrations from both providers and migrate:

   php artisan vendor:publish --provider="Bavix\Wallet\WalletServiceProvider"
   php artisan vendor:publish --provider="Bavix\Wallet\Uuid\UuidServiceProvider"
   php artisan migrate
   

3. Point config/wallet.php at the UUID model variants (wallet, transaction, transfer, transfer_lazy). Nothing works until those four keys are swapped — the default integer models will try to write to bigint columns.
4. First use case: give the User model the Wallet contract and create a wallet, then inspect the primary key. You should get a UUID string from $wallet->getKey() even if the column is binary(16) under the hood.

Look first at: the published migrations (they define the column type — this determines everything else), then config/wallet.php, then the package's UUID model classes you're now extending.

Implementation Patterns

Config swap, not code change. The intended integration is entirely through config/wallet.php. Swap the four model entries for the package's UUID models and all of laravel-wallet's internals (transactions, transfers, locks, refunds) follow automatically. This is why the package is small and why upgrading rarely touches application code.

Binary vs. string UUID. Pick per-project before writing migrations:

• binary(16) — smaller indexes, faster joins, better for high-volume ledgers. Requires casts to read/write sanely.
• char(36) — human-readable in the DB, easier ad-hoc SQL, larger indexes.

Decide once; converting later means rewriting every foreign key on wallets, transactions, transfers.

Extending rather than editing. Subclass the package models when you need extra behaviour (scopes, accessors, tenant columns) and register your subclasses in config. Same for Transfer/TransferLazy — the lazy variant must resolve to the same key type as the eager one, or transfers silently fail at the type level.

API layer. UUIDs are the whole point here: non-enumerable IDs in routes and JSON. Use route model binding on the UUID key, and expose $wallet->uuid / getKey() as a string rather than letting a binary column leak into a resource.

Multi-tenant and distributed writes. Because IDs are generated in PHP (not by the DB), you can create wallets/transactions without a round-trip and merge ledgers across shards/databases without ID collisions. Use ordered/sequential UUIDs if you need index locality.

Testing. RefreshDatabase plus the package migrations in your test suite; assert on the string UUID, never on the raw column value. The PHPUnit ^11 bump in this release only affects people running the package's own test suite — your application's PHPUnit version is unaffected.

Gotchas and Tips

• This major bump is a dependency signal, not a feature release. The changelog is almost entirely Dependabot/CI noise plus "add support laravel-wallet 12". Treat 4.0.0 as: requires laravel-wallet 12, and therefore likely drops older Laravel/PHP versions. Check composer.json constraints before assuming a drop-in upgrade from 3.0.1.
• Binary columns return raw bytes. If you choose binary(16), a naive ->getKey() or JSON serialize can produce mojibake. Ensure the uuid/binary_uuid cast (or the model's accessor) is active on every model that touches the column, including your own pivot/audit tables.
• Foreign key type drift. binary(16) vs char(36) mismatch is the single most common failure: MySQL accepts the migration and then joins return nothing. Copy the column definition verbatim from the published stub.
• Ordering. UUIDv4 primary keys are random — ORDER BY id is meaningless and index insert locality suffers. If your ledger queries sort by time, order by created_at (indexed) not by key, or use ordered UUIDs.
• Pagination. Cursor pagination on a random UUID key still works, but the cursor is opaque; don't mix it with id-based offsets when comparing across the two schemes.
• Mixing ID strategies mid-project. If you have existing integer-keyed wallets, migrating rows is a data task, not a config toggle. Run it in a maintenance window; transactions.wallet_id and both sides of transfers must be rewritten atomically.
• Debugging tip. When a wallet operation throws an opaque type error, dump $wallet->getKeyType() and $wallet->getIncrementing() (UUID models must set incrementing = false, keyType = 'string'). Most "it silently saves but can't be found" bugs are a model that reverted to the default integer base class.
• Extension points. Override uniqueIds()/newUniqueId() on your model if you need ULIDs, UUIDv7, or a prefixed ID format; the rest of the package only cares that the value is a non-incrementing scalar.