Laravel Wallet Laravel Package

Getting Started

• Start with the v1.2.0 change: the package can now return false instead of throwing UnacceptedTransactionException when a wallet has insufficient funds. Treat this as an opt-in control-flow feature for flows where insufficient balance is expected, such as checkout, withdrawals, or transfers.
• Minimal setup: install via Composer, publish/configure migrations and wallet config, run migrations, attach the package’s wallet capability to the relevant model, create/load a wallet, then test a small debit/credit flow.
• First practical use case: in a checkout or withdrawal service, enable the new “return false on insufficient wallet” behavior and branch on the boolean result to show a validation error or redirect. Keep the default exception behavior elsewhere so unexpected failures remain visible.
• Look first at the package config for the insufficient-wallet behavior, the exception class UnacceptedTransactionException, and the transaction/debit method return type. Confirm whether the option is global or per-call before adopting it broadly.

Implementation Patterns

• Use the default throwing behavior for internal accounting, jobs, and invariant-sensitive code where an insufficient wallet should fail loudly.

• Use the new false behavior at user-facing boundaries where insufficient funds is a normal outcome. Example pattern:

  $result = $wallet->debit($amount, $meta);
  
  if ($result === false) {
      // Expected insufficient-funds path: validation message, retry prompt, etc.
  }
  

• Centralize wallet operations in an application service rather than scattering debit/credit calls and exception handling across controllers. This keeps the chosen behavior consistent and makes it easy to switch modes later.

• If the package supports per-call or contextual configuration, prefer enabling false mode only for the specific operation that needs it. Avoid globally suppressing the exception unless the whole application treats insufficient funds as a boolean outcome.

• Wrap wallet mutations in database transactions where the package does not already do so, and keep wallet updates close to the related order/payment state changes.

• In queued jobs or retried operations, handle false explicitly. Do not let a retry loop spin forever on an expected insufficient-funds result.

• Add tests for both modes: one asserting UnacceptedTransactionException is thrown by default, and one asserting false is returned when the new behavior is enabled. Also test that successful debits still return/behave as expected.

Gotchas and Tips

• The new behavior changes control flow, not necessarily business meaning. A false result must not be treated as success or ignored; every caller must branch on it.
• Update return type hints and docblocks if methods can now return false in addition to their previous result type. Static analysis and IDE hints may otherwise miss the new path.
• Do not replace UnacceptedTransactionException handling blindly. If the option is enabled, existing catch (UnacceptedTransactionException $e) blocks may become dead code for insufficient funds, while still being needed for other failures.
• Clear and rebuild config cache after changing the new option. Laravel config caching can make it appear that the behavior did not change.
• Verify whether a failed debit that returns false leaves any partial state behind. Confirm the package rolls back or does not persist wallet/transaction records on insufficient funds, especially inside your own outer transactions.
• Keep concurrency in mind. A balance check that returns false is still subject to race conditions unless the package uses locking or atomic updates. Do not rely on a prior balance read alone.
• Treat false as an expected outcome for logging/metrics, but keep exceptions available for unexpected failures. Avoid catching and swallowing all wallet errors just to simplify controllers.
• The v1.2.0 change appears additive/opt-in, so it should not be breaking by itself. Still review every wallet call site after upgrading to ensure callers handle a possible boolean result if the option is enabled.
• Best extension point is usually an application-level wallet service wrapping the package. That lets you choose exception vs false behavior, add audit logging, and enforce transaction boundaries without forking package code.