ars / laravel-cashier
A powerful package for Laravel that facilitates seamless management of virtual currency, transaction handling, balance management, and fund transfers within your applications.
Requires
- php: >=8.0
- illuminate/support: >=9.0
README
A powerful package for Laravel that facilitates seamless management of virtual currency, transaction handling, balance management, and fund transfers within your applications.
Features
- Wallet Management: Create and manage wallets associated with users or other entities.
- Payment Handling: Manage payments, including initiation, processing, and transaction logging.
- Transaction Management: Record and track all wallet-related transactions, including deposits and withdrawals.
- Configurable Withdraw Ceiling: Set a ceiling limit for withdrawals through configuration.
Requirements:
- Laravel Version: 10 or higher
- PHP Version: 8.0 or higher
Installation
To install the package, use Composer:
composer require ars/laravel-cashier
After installation, publish the configuration and migration files:
php artisan vendor:publish --provider="Ars\Cashier\Providers\CashierServiceProvider"
Then, run the migrations:
php artisan migrate
Configuration
The package comes with a configuration file located at config/cashier.php
. Key configuration options include:
wallet.ceiling_withdraw
: The default withdrawal ceiling.tables
: Customizable table names for wallets, payments, and transactions.
return [ 'wallet' => [ 'ceiling_withdraw' => 0, ], 'tables' => [ 'wallet' => 'wallets', 'payment' => 'payments', 'transaction' => 'transactions', ], ];
Usage
Traits
HasWallet
Add the HasWallet
trait to any model that should have a wallet:
use Ars\Cashier\Models\Traits\HasWallet; class User extends Model { use HasWallet; }
-
Get Balance: Retrieve the wallet balance with:
$balance = $user->balance;
-
Deposit:
$user->deposit(100, ['description' => 'Initial deposit']);
This will increase the user’s wallet balance by 100 and log the transaction.
-
Withdraw:
$user->withdraw(50, ['description' => 'Purchase withdrawal']);
This will decrease the user’s wallet balance by 50, if within the allowable ceiling, and log the transaction.
-
Check Withdraw Capability:
if ($user->canWithdraw(50, 10)) { echo "Withdrawal allowed"; } else { echo "Withdrawal exceeds allowed limits"; }
HasPay
Add the HasPay
trait to any model that should handle payments:
use Ars\Cashier\Models\Traits\HasPay; class Order extends Model { use HasPay; }
-
Initiate Payment:
$payment = $order->requestPay('AUTH123', 200, ['order_id' => $order->id]);
This starts a payment process and logs it as a transaction.
-
Process Payment Result:
$result = $order->resultPay('AUTH123', '00', 'REF456');
This updates the payment details and marks the associated transaction as accepted.
-
Access Payment Transaction:
$transaction = $payment->transaction;
You can access the transaction associated with a specific payment.
Wallet Model
The Wallet
model manages user balances and transactions.
-
Get All Transactions:
$transactions = $wallet->transactions; foreach ($transactions as $transaction) { echo $transaction->amount . " - " . $transaction->type; }
-
Set Custom Withdrawal Ceiling:
$wallet->ceilingWithdraw = 500;
You can dynamically adjust the ceiling for withdrawals on a specific wallet.
Payment Model
The Payment
model handles payment processing and recording.
-
Retrieve Payment by Authority:
$payment = Payment::where('authority', 'AUTH123')->first();
This retrieves a payment record based on its authority code.
-
Update Payment Status:
$payment->update(['status_code' => '00', 'payed_at' => now()]);
This updates the status of a payment, which can be useful in payment processing callbacks.
License
This package is open-sourced software licensed under the MIT license.
Contributing
Contributions are welcome! Please submit a pull request or create an issue for any improvements or suggestions.
Support
For any issues, please visit the Issues page.