Merge pull request #824 from bavix/docs-float

[docs] documentation of float wallets has been expanded

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.

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)

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'.
      */

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!

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,23 +39,38 @@ $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?
 
 ```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! 

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);

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! 

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;
 }
 ```
 

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`