diff --git a/docs/_include/models/user_simple_float.md b/docs/_include/models/user_simple_float.md new file mode 100644 index 000000000..0547e8f13 --- /dev/null +++ b/docs/_include/models/user_simple_float.md @@ -0,0 +1,17 @@ +It is necessary to expand the model that will have the wallet. +This is done in two stages: + - Add `Wallet` interface; + - Add the `HasWalletFloat` trait; + +Let's get started. +```php +use Bavix\Wallet\Traits\HasWalletFloat; +use Bavix\Wallet\Interfaces\Wallet; + +class User extends Model implements Wallet +{ + use HasWalletFloat; +} +``` + +The model is prepared to work with a wallet. diff --git a/docs/_sidebar.md b/docs/_sidebar.md index a9d7e3c10..0acf17f85 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -24,6 +24,12 @@ - [Transfer](wallet-transfer) - [Transaction Filter](transaction-filter) +- Fractional Wallet + + - [Deposit](deposit-float) + - [Withdraw](withdraw-float) + - [Transfer](transfer-float) + - High performance api handles - [Batch transactions](batch-transactions) diff --git a/docs/configuration.md b/docs/configuration.md index 41d5f0220..05761ca98 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,7 +4,8 @@ Though this package is crafted to suit most of your needs by default, you can ed ## Configure default wallet Customize `name`,`slug` and `meta` of default wallet. -```php[config/wallet.php] +config/wallet.php: +```php 'default' => [ 'name' => 'Ethereum', 'slug' => 'ETH', @@ -15,7 +16,8 @@ Customize `name`,`slug` and `meta` of default wallet. You can extend base Wallet model by creating a new class that extends `Bavix\Wallet\Models\Wallet` and registering the new class in `config/wallet.php`. Example `MyWallet.php` -```php[App/Models/MyWallet.php] +App/Models/MyWallet.php: +```php use Bavix\Wallet\Models\Wallet as WalletBase; class MyWallet extends WalletBase { @@ -24,7 +26,8 @@ class MyWallet extends WalletBase { ``` ### Register base Wallet model -```php[config/wallet.php] +config/wallet.php: +```php 'wallet' => [ 'table' => 'wallets', 'model' => MyWallet::class, @@ -44,7 +47,8 @@ This same method above, can be used to extend the base `Transfer` and `Transacti You can change the default wallet decimal places, in wallet config file. This can be useful when working with fractional numbers. -```php[config/wallet.php] +config/wallet.php: +```php /** * Base model 'wallet'. */ diff --git a/docs/deposit-float.md b/docs/deposit-float.md new file mode 100644 index 000000000..a34f1a79d --- /dev/null +++ b/docs/deposit-float.md @@ -0,0 +1,40 @@ +# Deposit float + +A deposit is a sum of money which is part of the full price of something, +and which you pay when you agree to buy it. + +In this case, the Deposit is the replenishment of the wallet. + +--- + +## User Model + +[User Simple](_include/models/user_simple_float.md ':include') + +## Make a Deposit + +Find user: + +```php +$user = User::first(); +``` + +As the user uses `HasWalletFloat`, he will have `balance` property. +Check the user's balance. + +```php +$user->balance; // 0 +$user->balanceInt; // 0 +$user->balanceFloatNum; // 0 +``` + +The balance is zero, which is what we expected. + +```php +$user->depositFloat(10.1); +$user->balance; // 1010 +$user->balanceInt; // 1010 +$user->balanceFloatNum; // 10.1 +``` + +Wow! diff --git a/docs/new-wallet.md b/docs/new-wallet.md index 47b7c7b03..f1252fb95 100644 --- a/docs/new-wallet.md +++ b/docs/new-wallet.md @@ -6,16 +6,15 @@ You can create an unlimited number of wallets, but the `slug` for each wallet sh ## User Model -Add the `HasWallet`, `HasWallets` trait's and `Wallet` interface to model. +Add the `HasWallets` trait's and `Wallet` interface to model. ```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; + use HasWallets; } ``` @@ -27,14 +26,6 @@ Find user: $user = User::first(); ``` -As the user uses `HasWallet`, he will have `balance` property. -Check the user's balance. - -```php -$user->balance; // 0 -``` - -It is the balance of the wallet by default. Create a new wallet. ```php @@ -48,9 +39,7 @@ $user->hasWallet('my-wallet'); // bool(true) $wallet->deposit(100); $wallet->balance; // 100 - -$user->deposit(10); -$user->balance; // 10 +$wallet->balanceFloatNum; // 1.00 ``` ## How to get the right wallet? @@ -58,13 +47,30 @@ $user->balance; // 10 ```php $myWallet = $user->getWallet('my-wallet'); $myWallet->balance; // 100 +$myWallet->balanceFloatNum; // 1.00 +``` + +## Default Wallet + MultiWallet + +Is it possible to use the default wallet and multi-wallets at the same time? Yes. + +```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; +} ``` -## How to get the default wallet? +How to get the default wallet? ```php $wallet = $user->wallet; $wallet->balance; // 10 +$wallet->balanceFloatNum; // 0.10 ``` It worked! diff --git a/docs/transaction-filter.md b/docs/transaction-filter.md index 87948a591..f500c573e 100644 --- a/docs/transaction-filter.md +++ b/docs/transaction-filter.md @@ -20,6 +20,7 @@ Let's take a look at a livelier code example: ```php $user->transactions()->count(); // 0 +// Multi wallets and default wallet can be used together // default wallet $user->deposit(100); $user->wallet->deposit(200); diff --git a/docs/transfer-float.md b/docs/transfer-float.md new file mode 100644 index 000000000..a5b66934a --- /dev/null +++ b/docs/transfer-float.md @@ -0,0 +1,59 @@ +# Transfer + +Transfer in our system are two well-known [Deposit](deposit-float) and [Withdraw](withdraw-float) +operations that are performed in one transaction. + +The transfer takes place between wallets. + +--- + +## User Model + +[User Simple](_include/models/user_simple_float.md ':include') + +## Make a Transfer + +Find user: + +```php +$first = User::first(); +$last = User::orderBy('id', 'desc')->first(); // last user +$first->getKey() !== $last->getKey(); // true +``` + +As the user uses `HasWalletFloat`, he will have `balance` property. +Check the user's balance. + +```php +$fist->balanceFloatNum; // 100.00 +$last->balanceFloatNum; // 0 +``` + +The transfer will be from the first user to the second. + +```php +$first->transferFloat($last, 5); +$first->balanceFloatNum; // 95 +$last->balanceFloatNum; // 5 +``` + +It worked! + +## Force Transfer + +Check the user's balance. + +```php +$first->balanceFloatNum; // 100 +$last->balanceFloatNum; // 0 +``` + +The transfer will be from the first user to the second. + +```php +$first->forceTransferFloat($last, 500); +$first->balanceFloatNum; // -400 +$last->balanceFloatNum; // 500 +``` + +It worked! diff --git a/docs/wallet-transfer.md b/docs/wallet-transfer.md index 1d956584c..43cf830d0 100644 --- a/docs/wallet-transfer.md +++ b/docs/wallet-transfer.md @@ -9,16 +9,15 @@ The transfer takes place between wallets. ## User Model -Prepare the model, add the `HasWallet`, `HasWallets` trait's and `Wallet` interface. +Prepare the model, add the `HasWallets` trait's and `Wallet` interface. ```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; + use HasWallets; } ``` diff --git a/docs/withdraw-float.md b/docs/withdraw-float.md new file mode 100644 index 000000000..1755d026f --- /dev/null +++ b/docs/withdraw-float.md @@ -0,0 +1,61 @@ +# Withdraw + +When there is enough money in the account, you can transfer/withdraw +it or buy something in the system. + +Since the currency is virtual, you can buy any services on your website. +For example, priority in search results. + +--- + +## User Model + +[User Simple](_include/models/user_simple_float.md ':include') + +## Make a Withdraw + +Find user: + +```php +$user = User::first(); +``` + +As the user uses `HasWalletFloat`, he will have `balance` property. +Check the user's balance. + +```php +$user->balance; // 10000 +$user->balanceInt; // 10000 +$user->balanceFloatNum; // 100.00 +``` + +The balance is not empty, so you can withdraw funds. + +```php +$user->withdrawFloat(10); +$user->balance; // 9000 +$user->balanceInt; // 9000 +$user->balanceFloatNum; // 90.00 +``` + +It worked! + +## Force Withdraw + +Forced withdrawal is necessary for those cases when +the user has no funds. For example, a fine for spam. + +```php +$user->balanceFloatNum; // 90.00 +$user->forceWithdrawFloat(101); +$user->balanceFloatNum; // -11.00 +``` + +## And what will happen if the money is not enough? + +There can be two situations: + +- The user's balance is zero, then we get an error +`Bavix\Wallet\Exceptions\BalanceIsEmpty` +- If the balance is greater than zero, but it is not enough +`Bavix\Wallet\Exceptions\InsufficientFunds`