Laravel Wallet

https://github.com/bavix/laravel-wallet
Admin
Laravel Wallet is a comprehensive package for managing virtual wallets, payments, and transactions...
Tokens:36,382
Snippets:349
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-wallet-swap via Composer

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/additions/swap.md

Run this command in your project root to install the package using Composer.

```bash
composer req bavix/laravel-wallet-swap
```

--------------------------------

### Install bavix/laravel-wallet with Composer

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/_include/composer.md

Installs the bavix/laravel-wallet package via Composer. Run this command in your project root after setting up Composer autoloading.

```bash
composer req bavix/laravel-wallet
```

--------------------------------

### Find item and check cost

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/payment.md

Retrieves the first item and displays its product amount, which is 100 in this example.

```php
$item = Item::first();
$item->getAmountProduct($user); // 100
```

--------------------------------

### Find user and check balance

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/payment.md

Retrieves the first user and displays their balance, which is 100 in this example.

```php
$user = User::first();
$user->balance; // 100
```

--------------------------------

### Item model with unlimited product interface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/cart.md

Example of an Item model implementing ProductInterface for unlimited products. It requires the getAmountProduct and getMetaProduct methods.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\ProductInterface;

class Item extends Model implements ProductInterface
{
    use HasWallet;

    public function getAmountProduct(Customer $customer): int|string
    {
        return round($this->price * 100);
    }

    public function getMetaProduct(): ?array
    {
        return [
            'title' => $this->title, 
            'description' => 'Purchase of Product #' . $this->id,
        ];
    }
}
```

--------------------------------

### Register base Wallet model in config/wallet.php and usage example

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/configuration.md

Registers MyWallet as the model for the 'wallet' configuration, then shows how to call the custom helloWorld method on a user's wallet. The model class must be registered here for the custom method to be used.

```php
'wallet' => [
    'table' => 'wallets',
    'model' => MyWallet::class,
    'creating' => [],
    'default' => [
        'name' => 'Default Wallet',
        'slug' => 'default',
        'meta' => [],
    ],
],
```

```php
echo $user->wallet->helloWorld();
```

--------------------------------

### Add HasWallets trait and Wallet interface to User model

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/new-wallet.md

Required setup for a model to support multiple wallets. The model must implement the Wallet interface and use the HasWallets trait.

```php
use Bavix\Wallet\Traits\HasWallets;
use Bavix\Wallet\Interfaces\Wallet;

class User extends Model implements Wallet
{
    use HasWallets;
}
```

--------------------------------

### Purchase check with PurchaseQueryHandlerInterface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Example migration for purchase checks using PurchaseQuery and PurchaseQueryHandlerInterface. It creates a purchase query and checks if the transfer exists.

```php
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

$transfer = app(PurchaseQueryHandlerInterface::class)
    ->one(PurchaseQuery::create($customer, $product));

$isPurchased = (bool) $transfer;
```

--------------------------------

### Item model with limited product interface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/cart.md

Example of an Item model implementing ProductLimitedInterface for limited products. It requires the canBuy method to implement constraint logic. The comment suggests using PurchaseQuery and PurchaseQueryHandlerInterface for one-time purchase checks.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

class Item extends Model implements ProductLimitedInterface
{
    use HasWallet;

    public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
    {
        /**
         * This is where you implement the constraint logic. 
         * 
         * If the service can be purchased once, then
         *  return ! app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($customer, $this));
         */
        return true; 
    }
    
    public function getAmountProduct(Customer $customer): int|string
    {
        return round($this->price * 100);
    }

    public function getMetaProduct(): ?array
    {
        return [
            'title' => $this->title, 
            'description' => 'Purchase of Product #' . $this->id,
        ];
    }
}
```

--------------------------------

### Install laravel-wallet-uuid via Composer

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/additions/uuid.md

Install the laravel-wallet-uuid package via Composer. Run this in your project root to add the package that enables UUID/ULID support for Laravel Wallet.

```bash
composer req bavix/laravel-wallet-uuid
```

--------------------------------

### Exchange between wallets

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/additions/swap.md

Find wallets by slug and exchange 10 units from USD to RUB. The example shows balances before and after the exchange.

```php
$rub = $user->getWallet('rub');
$usd = $user->getWallet('usd');

$usd->balance; // 200
$rub->balance; // 0

$usd->exchange($rub, 10);
$usd->balance; // 190
$rub->balance; // 622
```

--------------------------------

### Publish Laravel Wallet Migrations

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/installation.md

Publishes the package's migration files to the application's database/migrations directory. Run this command after installing the package to customize the migration files before running them.

```bash
php artisan vendor:publish --tag=laravel-wallet-migrations
```

--------------------------------

### Item model with limited product quantity

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/basic-usage.md

Implements ProductLimitedInterface with canBuy method for constraint logic. Example returns true, so purchases are always allowed.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

class Item extends Model implements ProductLimitedInterface
{
    use HasWallet;

    public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
    {
        /**
         * This is where you implement the constraint logic. 
         * 
         * If the service can be purchased once, then
         *  return ! app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($customer, $this));
         */
        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,
        ];
    }
}
```

--------------------------------

### Purchase and refund with pay, safePay, and refund

Source: https://github.com/bavix/laravel-wallet/blob/master/README.md

Perform a purchase with pay, safePay, and refund methods. The pay method throws an exception if funds are insufficient. The example shows balance changes and purchase status checks.

```php
$user = User::first();
$user->balance; // 100

$item = Item::first();
$user->pay($item); // If you do not have enough money, throw an exception
var_dump($user->balance); // 0

if ($user->safePay($item)) {
  // try to buy again
}

var_dump((bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item))); // bool(true)

var_dump($user->refund($item)); // bool(true)
var_dump((bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item))); // bool(false)
```

--------------------------------

### Get a specific wallet by slug

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/new-wallet.md

Retrieves a wallet using its slug and shows its balance.

```php
$myWallet = $user->getWallet('my-wallet');
$myWallet->balance; // 100
$myWallet->balanceFloatNum; // 1.00
```

--------------------------------

### Custom TransactionDtoAssemblerInterface implementation with state tracking

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Shows a custom assembler that tracks transaction state using TransactionStateService and MathServiceInterface. It computes before/after balances and pushes state changes. The example includes a placeholder 'confirmado' variable that is not defined in the snippet.

```php
// Custom assembler with state tracking
final class StateAwareAssembler implements TransactionDtoAssemblerInterface
{
    public function __construct(
        private TransactionDtoAssembler $base,
        private TransactionStateService $stateService,  // Your instance
        private RegulatorServiceInterface $regulator,
        private MathServiceInterface $mathService,
    ) {}

    public function create(...): TransactionDtoInterface
    {
        $dto = $this->base->create(...);

        $before = $this->regulator->amount($payable);
        $after = $ confirmado
            ? $this->mathService->add($before, $amount)  // or sub for withdraw
            : $before;

        $this->stateService->push($dto->getUuid(), $walletId, [
            'balance' => $before,
        ], [
            'balance' => $after,
        ]);

        return $dto;
    }
}
```

--------------------------------

### Reset transaction confirmation with resetConfirm

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/cancel.md

Create a confirmed transaction and then reset its confirmation using the resetConfirm method. The example shows the balance before and after, and the confirmed flag changing from true to false.

```php
$user->balance; // 0
$transaction = $user->deposit(100); // confirmed transaction 
$transaction->confirmed; // bool(true)
$user->balance; // 100

$user->resetConfirm($transaction); // bool(true)
$transaction->confirmed; // bool(false)

$user->balance; // 0
```

--------------------------------

### Compare transactions() and walletTransactions() with multiple wallets

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/transaction-filter.md

Shows the difference between transactions() and walletTransactions(). The transactions() method returns all transactions for the wallet owner, while walletTransactions() filters to a specific wallet. The example creates multiple wallets and deposits/withdraws to illustrate the counts.

```php
$user->transactions()->count(); // 0

// Multi wallets and default wallet can be used together
// default wallet
$user->deposit(100);
$user->wallet->deposit(200);
$user->wallet->withdraw(1);

// usd
$usd = $user->createWallet(['name' => 'USD']);
$usd->deposit(100);

// eur
$eur = $user->createWallet(['name' => 'EUR']);
$eur->deposit(100);

$user->transactions()->count(); // 5
$user->wallet->transactions()->count(); // 5
$usd->transactions()->count(); // 5
$eur->transactions()->count(); // 5
// the transactions method returns data relative to the owner of the wallet, for all transactions

$user->walletTransactions()->count(); // 3. we get the default wallet
$user->wallet->walletTransactions()->count(); // 3
$usd->walletTransactions()->count(); // 1
$eur->walletTransactions()->count(); // 1
```

--------------------------------

### Update getAmountProduct method for version 4.x

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

In version 3.1.x to 4.0.x, the getAmountProduct method must accept a Customer $customer argument. The example shows the old and new signatures.

```php
    public function getAmountProduct(): int
    {
        return $this->price;
    }
```

```php
    public function getAmountProduct(Customer $customer): int
    {
        return $this->price;
    }
```

--------------------------------

### Creating transfers with client-side UUIDs (TransferQuery and TransferFloatQuery)

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/high-performance/batch-transfers.md

Since v10.0.0, you can create transactions and transfers with client-side generated UUIDs. The example shows both int and float versions (TransferQuery and TransferFloatQuery) with Extra options for deposit, withdraw, transfer UUIDs, and metadata. Keep UUIDs unique.

```php
use Bavix\Wallet\External\Api\TransferQuery;

// int version
new TransferQuery($from, $wallet, $amount, new \Bavix\Wallet\External\Dto\Extra(
    deposit: new \Bavix\Wallet\External\Dto\Option(
        null,
        uuid: '71cecafe-da10-464f-9e00-c80437bb4c3e', // deposit transaction
    ),
    withdraw: new \Bavix\Wallet\External\Dto\Option(
        null,
        uuid: '3805730b-39a1-419d-8715-0b7cc3f1ffc2', // withdraw transaction
    ),
    uuid: 'f8becf81-3993-43d7-81f1-7a725c72e976', // transfer uuid
    extra: ['info' => 'fast deposit'], // metadata in the table transfers
));

// float version
new TransferFloatQuery($from, $wallet, $amountFlaot, new \Bavix\Wallet\External\Dto\Extra(
    deposit: new \Bavix\Wallet\External\Dto\Option(
        null,
        uuid: '71cecafe-da10-464f-9e00-c80437bb4c3e', // deposit transaction
    ),
    withdraw: new \Bavix\Wallet\External\Dto\Option(
        null,
        uuid: '3805730b-39a1-419d-8715-0b7cc3f1ffc2', // withdraw transaction
    ),
    uuid: 'f8becf81-3993-43d7-81f1-7a725c72e976', // transfer uuid
    extra: ['info' => 'fast deposit'], // metadata in the table transfers
));
```

--------------------------------

### Create wallets and deposit initial funds

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/transfer.md

Creates wallets for the two users and deposits 100 into the first wallet, showing balances.

```php
$firstWallet = $first->createWallet(['name' => 'First User Wallet']);
$lastWallet = $last->createWallet(['name' => 'Second User Wallet']);

$firstWallet->deposit(100);
$firstWallet->balance; // 100
$lastWallet->balance; // 0
```

--------------------------------

### Get current balance

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/refresh.md

Shows the user's current balance before confirming unconfirmed transactions.

```php
$user->id; // 5
$user->balance; // 27
```

--------------------------------

### Extend base Wallet model with MyWallet class (App/Models/MyWallet.php)

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/configuration.md

Shows how to create a custom Wallet model extending Bavix\Wallet\Models\Wallet, adding a helloWorld method. Save as App/Models/MyWallet.php.

```php
use Bavix\Wallet\Models\Wallet as WalletBase;

class MyWallet extends WalletBase {
    public function helloWorld(): string { return "hello world"; }
}
```

--------------------------------

### Fill the cart and pay

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/cart.md

Create a cart, add items with quantities, calculate total, deposit funds, and pay for the cart. Demonstrates using the Cart object and payCart method.

```php
use Bavix\Wallet\Objects\Cart;

$list = [
    'potato' => 3,
    'carrot' => 10,
];

$products = Item::query()
    ->whereIn('slug', ['potato', 'carrot'])
    ->get();

$cart = app(Cart::class);
foreach ($products as $product) {
    $cart = $cart->withItem($product, quantity: $list[$product->slug]);
}

$cartTotal = $cart->getTotal($user); // 15127
$user->deposit($cartTotal); 
$user->balanceInt; // 15127
$user->balanceFloat; // 151.27

$cart = $cart->withItem(current($products), pricePerItem: 500); // 15127+500
$user->deposit(500);
$user->balanceInt; // 15627
$user->balanceFloat; // 156.27

(bool)$user->payCart($cart); // true
$user->balanceFloat; // 0
```

--------------------------------

### Get the default wallet

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/new-wallet.md

Accesses the default wallet via the wallet property and shows its balance.

```php
$wallet = $user->wallet;
$wallet->balance; // 10
$wallet->balanceFloatNum; // 0.10
```

--------------------------------

### Find product and check price

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/gift.md

Finds the product and checks its price and balance. The product price is 100 and its balance is 0.

```php
$item = Item::first();
$item->getAmountProduct($first); // 100
$item->balance; // 0
```

--------------------------------

### Configure default wallet (name, slug, meta) in config/wallet.php

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/configuration.md

Defines the default wallet configuration with name 'Ethereum', slug 'ETH', and an empty meta array. Place this in the 'default' key of config/wallet.php.

```php
'default' => [
    'name' => 'Ethereum',
    'slug' => 'ETH',
    'meta' => [],
],
```

--------------------------------

### Create wallets with currency

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/additions/swap.md

Create two wallets with currency metadata (USD and RUB) using the createWallet method.

```php
$usd = $user->createWallet([
    'name' => 'My Dollars',
    'slug' => 'usd',
    'meta' => ['currency' => 'USD'],
]);

$rub = $user->createWallet([
    'name' => 'My Ruble',
    'slug' => 'rub',
    'meta' => ['currency' => 'RUB'],
]);
```

--------------------------------

### 6.x mathable configuration

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Your code on 6.x for the 'mathable' config key, directly using BrickMath::class.

```php
    'mathable' => BrickMath::class,
```

--------------------------------

### Find Item and Create Receiving Wallet

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/receiving.md

Finds the first item, checks its cost, and creates a receiving wallet for the item with a name and meta information.

```php
$item = Item::first();
$item->getAmountProduct($user); // 100

$receiving = $item->createWallet([
    'name' => 'Dollar',
    'meta' => [
        'currency' => 'USD',
    ],
]);

```

--------------------------------

### Set credit limit and pay with wallet

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/credit-limits.md

Sets a credit limit of 10000 on the default wallet, then pays for a product, resulting in a negative balance. The credit limit is stored in the wallet's meta as 'credit'.

```php
/**
 * @var \Bavix\Wallet\Interfaces\Customer $customer
 * @var \Bavix\Wallet\Models\Wallet $wallet
 * @var \Bavix\Wallet\Interfaces\ProductInterface $product
 */
$wallet = $customer->wallet; // get default wallet
$wallet->meta['credit'] = 10000; // credit limit
$wallet->save(); // update credit limit

$wallet->balanceInt; // 0
$product->getAmountProduct($customer); // 500

$wallet->pay($product); // success
$wallet->balanceInt; // -500
```

--------------------------------

### Create a new wallet and perform operations

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/new-wallet.md

Checks if a wallet with the given slug exists, creates a new wallet, verifies its existence, and deposits funds. The balance is shown in integer and float formats.

```php
$user->hasWallet('my-wallet'); // bool(false)
$wallet = $user->createWallet([
    'name' => 'New Wallet',
    'slug' => 'my-wallet',
]);

$user->hasWallet('my-wallet'); // bool(true)

$wallet->deposit(100);
$wallet->balance; // 100
$wallet->balanceFloatNum; // 1.00
```

--------------------------------

### Filter transactions for a single wallet with walletTransactions()

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/transaction-filter.md

Use this method to get a query builder for transactions of a specific wallet instance, rather than all transactions for the wallet owner. The variable $wallet must be an instance of Bavix\Wallet\Models\Wallet.

```php
/** @var \Bavix\Wallet\Models\Wallet $wallet */

$query = $wallet->walletTransactions();
```

--------------------------------

### Purchase flow with pay, safePay, refund and PurchaseQuery

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/basic-usage.md

Demonstrates paying for an item, handling insufficient funds, safePay for non-throwing purchase, and refund. Useless? Includes checks with PurchaseQueryHandlerInterface.

```php
$user = User::first();
$user->balance; // 100

$item = Item::first();
$user->pay($item); // If you do not have enough money, throw an exception
var_dump($user->balance); // 0

if ($user->safePay($item)) {
  // try to buy again )
}

var_dump((bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item))); // bool(true)

var_dump($user->refund($item)); // bool(true)
var_dump((bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item))); // bool(false)
```

--------------------------------

### Register Wallet State Projector in config

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/events/wallet-state-projection.md

Adds the projector class to the 'projectors' configuration under the 'wallet' key. This is required to enable the custom wallet fields.

```php
'projectors' => [
    'wallet' => \App\Wallet\WalletStateBatchProjector::class,
],
```

--------------------------------

### Implement WalletBatchProjectorInterface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/events/wallet-state-projection.md

Implements the WalletBatchProjectorInterface to project custom wallet fields. The project method receives balances and wallets, and returns rows with balance_after, held_balance, and state_hash. Uses hash('sha256', ...) for state_hash.

```php
use Bavix\Wallet\Internal\Projector\WalletBatchProjectorInterface;

final readonly class WalletStateBatchProjector implements WalletBatchProjectorInterface
{
    public function project(array $balances, array $walletsById): array
    {
        $rows = [];
        foreach ($balances as $walletId => $resultingBalance) {
            $wallet = $walletsById[$walletId] ?? null;
            if ($wallet === null) {
                continue;
            }

            $heldBalance = (string) ($wallet->getAttribute('held_balance') ?? '0');
            $rows[$walletId] = [
                'balance_after' => $resultingBalance,
                'held_balance' => $heldBalance,
                'state_hash' => hash('sha256', $wallet->uuid.':'.$resultingBalance.':'.$heldBalance),
            ];
        }

        return $rows;
    }
}
```

--------------------------------

### Make a Deposit

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/deposit.md

Deposits 10 cents to the user's wallet and verifies the updated balance.

```php
$user->deposit(10); 
$user->balance; // 10
$user->balanceInt; // 10
```

--------------------------------

### Batch transfers with TransferQueryHandlerInterface::apply

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/high-performance/batch-transfers.md

High-performance batch transfer using TransferQueryHandlerInterface::apply. The package optimizes queries and executes them in a single transaction. It does not check wallet balances before transferring, so you must handle that yourself. Avoid creating large packs to prevent request queuing.

```php
use Bavix\Wallet\External\Api\TransferQuery;
use Bavix\Wallet\External\Api\TransferQueryHandlerInterface;

app(TransferQueryHandlerInterface::class)->apply(
    array_map(
        static fn (Wallet $wallet) => new TransferQuery($from, $wallet, $amount, null),
        $wallets
     )
);
```

--------------------------------

### Create multi-wallet with credit limit

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/credit-limits.md

Creates a new wallet with a credit limit of 500 by passing 'credit' in the meta array.

```php
/** @var \Bavix\Wallet\Traits\HasWallets $user */
$wallet = $user->createWallet([
    'name' => 'My Wallet',
    'meta' => ['credit' => 500],
]);
```

--------------------------------

### Convert balance to fractional number with floatValue

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/helpers/formatter.md

Use FormatterServiceInterface::floatValue to convert a numeric string to a float with a given number of decimal places. The second argument specifies the number of decimals. Example: '12345' with 2 decimals becomes 123.45.

```php
app(FormatterServiceInterface::class)->floatValue('12345', 2); // 123.45
app(FormatterServiceInterface::class)->floatValue('12345', 3); // 12.345
```

--------------------------------

### Convert balance to whole number with intValue

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/helpers/formatter.md

Use FormatterServiceInterface::intValue to convert a numeric string to an integer by removing the decimal point. The second argument specifies the number of decimal places in the input. Example: '12.345' with 3 decimals becomes 12345.

```php
app(FormatterServiceInterface::class)->intValue('12.345', 3); // 12345
app(FormatterServiceInterface::class)->intValue('123.45', 2); // 12345
```

--------------------------------

### Pay for product with MerchantFeeDeductible and MinimalTaxable

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/merchant-fee-deductible.md

Executes the payment with $user->pay($item). The customer pays the product price (100) and the merchant receives the product price minus the minimal fee (5), resulting in 95. After payment, the user's balance is 0.

```php
$user->pay($item); // success, customer pays $100
$user->balance; // 0
```

--------------------------------

### Configure cache service in wallet.php

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/db/race-condition.md

Configuration for the cache service in wallet.php. It stores the state of wallet balances. The 'driver' should be set to 'redis' for recommended performance.

```php
    /**
     * Storage of the state of the balance of wallets.
     */
    'cache' => ['driver' => 'array'],
```

--------------------------------

### Atomic block() with wallet lock and transaction

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/db/atomic-service.md

Use the AtomicServiceInterface::block() method to atomically apply actions to both a user entity and a wallet in one transaction. The wallet is locked and a transaction is started immediately, so if the wallet has insufficient funds, the operation failsched and the transaction rolls back, releasing the lock.

```php
use Bavix\Wallet\Services\AtomicServiceInterface;

app(AtomicServiceInterface::class)->block($wallet, function () use ($wallet, $entity) {
    $entity->increaseSales(); // update entity set sort_at=NOW() where id=123;
    $wallet->withdraw(100);
});
```

--------------------------------

### Implement custom event assembler

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/events/customize.md

Create an assembler class that implements BalanceUpdatedEventAssemblerInterface. The create method returns a new MyUpdatedEvent instance with the wallet and a new DateTimeImmutable.

```php
use Bavix\Wallet\Internal\Assembler\BalanceUpdatedEventAssemblerInterface;

class MyUpdatedEventAssembler implements BalanceUpdatedEventAssemblerInterface
{
    public function create(\Bavix\Wallet\Models\Wallet $wallet) : \Bavix\Wallet\Internal\Events\BalanceUpdatedEventInterface
    {
        return new MyUpdatedEvent($wallet, new DateTimeImmutable());
    }
}
```

--------------------------------

### Implement MyBalanceUpdatedListener

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/events/balance-updated-event.md

Create a listener class with a handle method that receives the BalanceUpdatedEventInterface. Implement your logic inside the method.

```php
use Bavix\Wallet\Internal\Events\BalanceUpdatedEventInterface;

class MyBalanceUpdatedListener
{
    public function handle(BalanceUpdatedEventInterface $event): void
    {
        // And then the implementation...
    }
}
```

--------------------------------

### Pay for product with MerchantFeeDeductible

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/merchant-fee-deductible.md

Executes the payment with $user->pay($item). The customer pays the product price (100) and the merchant receives the product price minus the fee. After payment, the user's balance is 0.

```php
$user->pay($item); // success, customer pays $100 (product price)
$user->balance; // 0
```

--------------------------------

### Create wallet with currency meta

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/exchange.md

Creates a wallet with a currency specified in the meta field. The currency is used for exchange operations.

```php
$user->createWallet([
    'name' => 'My USD Wallet',
    'meta' => ['currency' => 'USD'],
]);
```

--------------------------------

### 5.x mathable configuration

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Your code on 5.x for the 'mathable' config key, using the $mathClass variable.

```php
    'mathable' => $mathClass,
```

--------------------------------

### Command Handler Creating Wallet with UUID

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/cqrs/create-wallet.md

Command handler that processes the CreateWalletCommandMessage and creates the wallet asynchronously using the provided UUID and name.

```php
public function __invoke(CreateWalletCommandMessage $message): void
{
    $user = $message->getUser();
    $user->createWallet([
        'uuid' => $message->getWalletUuid(),
        'name' => $message->getWalletName(),
    ]);
}
```

--------------------------------

### Check initial balance

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/fractional/deposit.md

Displays the initial balance properties of the user, all zero before any deposit.

```php
$user->balance; // 0
$user->balanceInt; // 0
$user->balanceFloatNum; // 0
```

--------------------------------

### Configure lock service in wallet.php

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/db/race-condition.md

Configuration for the lock service in wallet.php. The 'driver' should be set to a provider that supports locks, such as 'redis', to enable race condition handling. The 'seconds' option sets the lock duration.

```php
    /**
     * A system for dealing with race conditions.
     */
    'lock' => [
        'driver' => 'array',
        'seconds' => 1,
    ],
```

--------------------------------

### Action Handler Dispatching CreateWalletCommandMessage

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/cqrs/create-wallet.md

Action handler that receives a wallet creation request, dispatches a CreateWalletCommandMessage asynchronously, and returns a 202 Accepted response.

```php
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Response as ResponseFactory;
...

public function __invoke(User $user, Request $request): Response
{
    $name = $request->get('wallet_name');
    $uuid = $request->get('wallet_uuid');

    $message = new CreateWalletCommandMessage($user, $name, $uuid);
    dispatch($message);

    return ResponseFactory::json([], 202);
}
```

--------------------------------

### 5.x code without type hints

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Your code on 5.x for the goods methods, with return types removed.

```php
    public function getAmountProduct(Customer $customer) { ... }

    public function getFeePercent() { ... }

    public function getMinimalFee() { ... }
```

--------------------------------

### User Model with HasWallet and HasWallets Traits

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/cqrs/create-wallet.md

Adds the HasWallet and HasWallets traits and implements the Wallet interface on the User model to enable wallet creation.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Traits\HasWallets;
use Bavix\Wallet\Interfaces\Wallet;

class User extends Model implements Wallet
{
    use HasWallet, HasWallets;
}
```

--------------------------------

### Simple wallet transactions

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/basic-usage.md

Shows how to use deposit, withdraw, and forceWithdraw on a User model. forceWithdraw can overspend, resulting in a negative balance.

```php
$user = User::first();
$user->balance; // 0

$user->deposit(10);
$user->balance; // 10

$user->withdraw(1);
$user->balance; // 9

$user->forceWithdraw(200, ['description' => 'payment of taxes']);
$user->balance; // -191
```

--------------------------------

### Check balances before transfer with meta

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/transfer.md

Shows the integer balances of the two wallets before a transfer with custom metadata.

```php
$firstWallet->balanceInt; // 1_000
$secondWallet->balanceInt; // 0
```

--------------------------------

### 4.x code with type hints

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Your code on 4.x for the goods methods, showing return types int and float.

```php
    public function getAmountProduct(Customer $customer): int  { ... }

    public function getFeePercent(): float  { ... }

    public function getMinimalFee(): int { ... }
```

--------------------------------

### Find users and check balances

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/gift.md

Finds the first and last users and checks their balances. The first user has a balance of 115, the last has 0.

```php
$first = User::first(); 
$last = User::orderBy('id', 'desc')->first(); // last user
$first->getKey() !== $last->getKey(); // true

$first->balance; // 115
$last->balance; // 0
```

--------------------------------

### Purchase with Cart and Receiving Wallet

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/receiving.md

Builds a cart with the item and the receiving wallet, then pays the cart. After payment, the user's balance is 0 and the receiving wallet has $100.

```php
$cart = app(Cart::class)
    ->withItem($item, receiving: $receiving)
;

$user->payCart($cart);
$user->balance; // 0

$receiving->balanceInt; // $100

```

--------------------------------

### Item Model with Taxable and ProductLimitedInterface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/commissions.md

Add the HasWallet trait and ProductLimitedInterface (or ProductInterface) and Taxable interfaces to the Item model. Implements canBuy, getAmountProduct, getMetaProduct, and getFeePercent (3% fee).

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\Taxable;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

class Item extends Model implements ProductLimitedInterface, Taxable
{
    use HasWallet;

    public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
    {
        /**
         * If the service can be purchased once, then
         *  return ! app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($customer, $this));
         */
        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,
        ];
    }

    public function getFeePercent()
    {
        return 0.03; // 3%    
    }
}

```

--------------------------------

### Item model with MerchantFeeDeductible and getFeePercent

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/merchant-fee-deductible.md

Item model implementing ProductLimitedInterface and MerchantFeeDeductible. Must implement getFeePercent() because MerchantFeeDeductible extends Taxable. The fee percentage must be between 0 and 100.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\MerchantFeeDeductible;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

class Item extends Model implements ProductLimitedInterface, MerchantFeeDeductible
{
    use HasWallet;

    public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
    {
        /**
         * If the service can be purchased once, then
         *  return ! app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($customer, $this));
         */
        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. For example, the product costs $100, the fee is 5%.
     * With MerchantFeeDeductible, customer pays $100, merchant receives $95.
     *
     * Minimum 0; Maximum 100
     */
    public function getFeePercent(): float|int
    {
        return 5.0; // 5%
    }
}
```

--------------------------------

### Batch deposit using TransactionQueryHandlerInterface

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/high-performance/batch-transactions.md

Uses the new API to create deposit queries for all wallets and apply them in a batch. This improves performance by combining insert queries. Note that this handle does not check wallet balance.

```php
use Bavix\Wallet\External\Api\TransactionQuery;
use Bavix\Wallet\External\Api\TransactionQueryHandlerInterface;

app(TransactionQueryHandlerInterface::class)->apply(
    array_map(
        static fn (Wallet $wallet) => TransactionQuery::createDeposit($wallet, $amount, null),
        $wallets
     )
);
```

--------------------------------

### Custom exchange service implementation

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/single/exchange.md

Implements a custom exchange service using a hardcoded rates array. The constructor computes reverse rates using the math service. The convertTo method multiplies the amount by the rate, defaulting to 1 if the pair is missing.

```php
use Bavix\Wallet\Internal\Service\MathServiceInterface;
use Bavix\Wallet\Services\ExchangeServiceInterface;

class MyExchangeService implements ExchangeServiceInterface
{
    private array $rates = [
        'USD' => [
            'RUB' => 67.61,
        ],
    ];

    private MathServiceInterface $mathService;

    public function __construct(MathServiceInterface $mathService)
    {
        $this->mathService = $mathService;

        foreach ($this->rates as $from => $rates) {
            foreach ($rates as $to => $rate) {
                if (empty($this->rates[$to][$from])) {
                    $this->rates[$to][$from] = $this->mathService->div(1, $rate);
                }
            }
        }
    }

    /** @param float|int|string $amount */
    public function convertTo(string $fromCurrency, string $toCurrency, $amount): string
    {
        return $this->mathService->mul($amount, $this->rates[$fromCurrency][$toCurrency] ?? 1);
    }
}
```

--------------------------------

### Republish wallet config with artisan vendor:publish

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Run this command to overwrite the existing config/wallet.php with the new default configuration. Use --force to overwrite without confirmation. After running, you must re-apply your custom settings.

```bash
php artisan vendor:publish --tag=laravel-wallet-config --force
```

--------------------------------

### Perform a standard transfer

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/multi/transfer.md

Transfers 5 from the first wallet to the last wallet, updating balances.

```php
$firstWallet->transfer($lastWallet, 5); 
$firstWallet->balance; // 95
$lastWallet->balance; // 5
```

--------------------------------

### Find user and check balance

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/cart.md

Retrieve the first user and check their balance. The balance is initially 0.

```php
$user = User::first();
$user->balance; // 0
```

--------------------------------

### Purchase with payFree

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/payment-free.md

Performs a free purchase using payFree. The purchase is confirmed via PurchaseQueryHandlerInterface, and the balances remain unchanged (user: 100, item: 0).

```php
$user->payFree($item);
(bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item)); // bool(true)
$user->balance; // 100
$item->balance; // 0
```

--------------------------------

### Implement custom event with broadcast support

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/events/customize.md

Create a custom event class that implements BalanceUpdatedEventInterface and ShouldBroadcast. The constructor takes a Wallet and DateTimeImmutable. The broadcastOn method returns the wallet's attributes.

```php
use Bavix\Wallet\Internal\Events\BalanceUpdatedEventInterface;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;

final class MyUpdatedEvent implements BalanceUpdatedEventInterface, ShouldBroadcast
{
    public function __construct(
        private \Bavix\Wallet\Models\Wallet $wallet,
        private DateTimeImmutable $updatedAt,
    ) {}
    
    public function getWalletId(): int { return $this->wallet->getKey(); }
    public function getWalletUuid(): string { return $this->wallet->uuid; }
    public function getBalance(): string { return $this->wallet->balanceInt; }
    public function getUpdatedAt(): DateTimeImmutable { return $this->updatedAt; }

    public function broadcastOn(): array
    {
        return $this->wallet->getAttributes();
    }
}
```

--------------------------------

### Give a gift with gift()

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/gift.md

The first user gives the product as a gift to the last user. After the gift, the first user's balance is 15, the last user's is 0, and the item's balance is 100. If the product uses the Taxable interface, Santa pays tax; if it uses MerchantFeeDeductible, the fee is deducted from the merchant's payout.

```php
$first->gift($last, $item);
(bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($last, $item, true)); // bool(true)
$first->balance; // 15
$last->balance; // 0
$item->balance; // 100
```

--------------------------------

### Item model with unlimited product quantity

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/basic-usage.md

Implements ProductInterface with methods to define product price and metadata. Returns 100 as the product amount.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\ProductInterface;

class Item extends Model implements ProductInterface
{
    use HasWallet;

    public function getAmountProduct(Customer $customer): int|string
    {
        return 100;
    }

    public function getMetaProduct(): ?array
    {
        return [
            'title' => $this->title, 
            'description' => 'Purchase of Product #' . $this->id,
        ];
    }
}
```

--------------------------------

### Publish laravel-wallet config

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/db/race-condition.md

Publishes the laravel-wallet configuration file into the project. Required before configuring the lock and cache services.

```bash
php artisan vendor:publish --tag=laravel-wallet-config
```

--------------------------------

### Implement Wallet Interface and HasWallet Trait in User Model

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/_include/models/user_simple.md

Add the Wallet interface and HasWallet trait to the model class. The model must implement the Wallet interface and use the HasWallet trait to be prepared for wallet operations.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Wallet;

class User extends Model implements Wallet
{
    use HasWallet;
}
```

--------------------------------

### Add HasWallet trait with ProductLimitedInterface

Source: https://github.com/bavix/laravel-wallet/blob/master/README.md

Add the HasWallet trait and ProductLimitedInterface to the Item model for limited product purchases. Implement the canBuy method to enforce purchase constraints.

```php
use Bavix\Wallet\Traits\HasWallet;
use Bavix\Wallet\Interfaces\Customer;
use Bavix\Wallet\Interfaces\ProductLimitedInterface;
use Bavix\Wallet\External\Api\PurchaseQuery;
use Bavix\Wallet\External\Api\PurchaseQueryHandlerInterface;

class Item extends Model implements ProductLimitedInterface
{
    use HasWallet;

    public function canBuy(Customer $customer, int $quantity = 1, bool $force = false): bool
    {
        /**
         * This is where you implement the constraint logic.
         *
         * If the service can be purchased once, then
         *  return ! app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($customer, $this));
         */
        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,
        ];
    }
}
```

--------------------------------

### Run artisan bx:transfer:fix to migrate transfer storage

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/introduction/upgrade.md

Execute this Artisan command to fix the transfer structure after upgrading to v9.0.0. If the command fails, restart it until it runs without errors.

```bash
artisan bx:transfer:fix
```

--------------------------------

### Eager loading with with method to reduce queries

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/_include/eager_loading.md

Use the with method to eager load the wallet relationship, reducing the operation to just 2 queries.

```php
$users = User::with('wallet')->all();
```

--------------------------------

### Refund item and check balances

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/purchases/refund.md

Performs the refund: first uses PurchaseQueryHandlerInterface to process the purchase query, then calls $user->refund($item). After the refund, the item balance becomes 0 and the user balance becomes 100.

```php
(bool) app(PurchaseQueryHandlerInterface::class)->one(PurchaseQuery::create($user, $item)); // bool(true)
(bool)$user->refund($item); // bool(true)
$item->balance; // 0
$user->balance; // 100
```

--------------------------------

### Batch withdraw with balance check

Source: https://github.com/bavix/laravel-wallet/blob/master/docs/guide/high-performance/batch-transactions.md

Combines AtomicServiceInterface, ConsistencyServiceInterface, and TransactionQueryHandlerInterface to check each wallet's balance before batch withdrawal. This ensures consistency but adds overhead.

```php
use Bavix\Wallet\External\Api\TransactionQuery;
use Bavix\Wallet\External\Api\TransactionQueryHandlerInterface;
use Bavix\Wallet\Services\AtomicServiceInterface;
use Bavix\Wallet\Services\ConsistencyServiceInterface;

app(AtomicServiceInterface::class)->blocks($wallets, function () use ($wallets, $amount) {
    foreach ($wallets as $wallet) {
        app(ConsistencyServiceInterface::class)->checkPotential($wallet, $amount);
    }

    app(TransactionQueryHandlerInterface::class)->apply(
        array_map(
            static fn (Wallet $wallet) => TransactionQuery::createWithdraw($wallet, $amount, null),
            $wallets
        )
    );
});
```
Tokens:
Raw