repository·master·Indexed 23 days ago
https://github.com/bavix/laravel-walletA library for managing virtual wallets, transactions, and purchases within Laravel applications. It provides tools for deposits, withdrawals, and purchasing systems via Customer and Product interfaces. The package supports integer and floating-point balances, eager loading to prevent N+1 queries, and atomic operations via AtomicServiceInterface. Additional extensions include laravel-wallet-swap for exchanging balances and laravel-wallet-uuid for UUID/ULID identifier support.
laravel-wallet is a package designed to make it easy to implement and manage virtual wallets within a Laravel application. It provides the necessary abstractions to handle balances, transactions, and financial logic for users or other entities.In a multi-wallet environment, the distinction between the owner's global transaction history and a specific wallet's history is handled by two different methods:
$user->transactions() returns the sum of all transactions across all wallets owned by the user.$wallet->walletTransactions() returns only the transactions that occurred within that specific wallet.Example behavior:
$user->transactions()->count() will return 4, while $usd->walletTransactions()->count() will return 1.By default, the Taxable interface adds fees to the customer's payment (Customer pays Price + Fee).
If you want the customer to pay only the product price and have the fee deducted from the merchant's payout instead, implement the MerchantFeeDeductible interface in your Item model.
Comparison:
The MerchantFeeDeductible interface allows you to implement a fee structure where the customer pays only the listed product price, and the fee is deducted from the merchant's payout. This is the opposite of the Taxable interface, where fees are added to the customer's payment.
Comparison:
HasWallet (singular) and HasWallets (plural) traits. The HasWallet trait allows you to access the default wallet via the $user->wallet property.If you need to perform operations involving multiple wallets simultaneously (for example, debiting from two different wallets at once), use the blocks() method.
This method locks all provided wallets and starts a transaction. The entire operation is considered successful only if all actions within the closure succeed. If any single operation fails (e.g., one wallet has insufficient funds), the entire operation is canceled and rolled back.
Note: Using blocks() is an expensive operation as it generates $N$ requests to the lock service, where $N$ is the number of wallets provided.
use Bavix\Wallet\Services\AtomicServiceInterface;
app(AtomicServiceInterface::class)->blocks([$wallet1, $wallet2], function () use ($wallet1, $wallet2) {
$wallet1->withdraw(100);
$wallet2->withdraw(100);
});::with('balance') method call with ::with('wallet').To use wallets and the swap functionality, your model (e.g., User) must implement the Bavix\Wallet\Interfaces\Wallet interface and use the HasWallet and HasWallets traits.
use Bavix\Wallet\Interfaces\Wallet;
use Bavix\Wallet\Traits\HasWallets;
use Bavix\Wallet\Traits\HasWallet;
class User extends Model implements Wallet
{
use HasWallet, HasWallets;
}To make an item (product) deduct fees from the merchant, implement the MerchantFeeDeductible interface (which extends Taxable) and the ProductInterface or ProductLimitedInterface. You must also include the HasWallet trait.
Required methods:
getFeePercent(): Returns the fee percentage (0 to 100).use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\MerchantFeeDeductible;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
class Item extends Model implements ProductLimitedInterface, MerchantFeeDeductible
{
use HasWallet;
public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
{
return true;
}
public function getAmountProduct(Customer $customer): int|string
{
return 100;
}
public function getMetaProduct(): ?array
{
return [
'title' => $this->title,
'description' => 'Purchase of Product #' . $this->id,
];
}
/**
* Specify the percentage of the amount.
* Minimum 0; Maximum 100
*/
public function getFeePercent(): float|int
{
return 5.0; // 5%
}
}Once you have implemented your ExchangeServiceInterface, you must register it in the config/wallet.php configuration file so the library can resolve it. Add your class name to the services.exchange key.
return [
// ...
'services' => [
'exchange' => MyExchangeService::class,
// ...
],
// ...
];If a product has constraints on how many times it can be purchased (e.g., a one-time service), implement ProductLimitedInterface on your Item model.
You must implement the canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool method to define your constraint logic.
Recommendation: For shopping cart implementations, do not use the limited interface. Instead, use PurchaseQuery and PurchaseQueryHandlerInterface as the primary API for checking purchase availability.
use Bavix//
use Bavix//
use Bavix//
use Bavix//
class Item extends Model implements ProductLimitedInterface
{
use HasWallet;
public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
{
// Implement constraint logic here
return true;
}
public function getAmountProduct(Customer $customer): int|string
{
return 100;
}
public function getMetaProduct(): ?array
{
return [
'title' => $this->title,
'description' => 'Purchase of Product #' . $this->id,
];
}
}Replace the getAvailableBalance method with either the getAvailableBalanceAttribute method or the available_balance property.