PHPackages                             hwallet/laravel-multi-wallet - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. hwallet/laravel-multi-wallet

ActiveLibrary

hwallet/laravel-multi-wallet
============================

A comprehensive Laravel package for managing multi-currency wallets with advanced features including multiple balance types, transfers, fees, and configurable exchange rates.

14[5 PRs](https://github.com/mohamedhabibwork/laravel-multi-wallet/pulls)PHPCI passing

Since Aug 20Pushed 1mo agoCompare

[ Source](https://github.com/mohamedhabibwork/laravel-multi-wallet)[ Packagist](https://packagist.org/packages/hwallet/laravel-multi-wallet)[ RSS](/packages/hwallet-laravel-multi-wallet/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (6)Used By (0)

Laravel Multi-Currency Wallet Management Package
================================================

[](#laravel-multi-currency-wallet-management-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/1e6ed6d25e122745c4d154badd15f5bc3ef8d48cdb7d8d2a1c3d6111a77e4d75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6f68616d65646861626962776f726b2f6c61726176656c2d6d756c74692d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hwallet/laravel-multi-wallet)[![GitHub Tests Action Status](https://camo.githubusercontent.com/3d74c3e6254a4447a82e2748178c405c65e12574320a6596949f666a24178847/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6f68616d65646861626962776f726b2f6c61726176656c2d6d756c74692d77616c6c65742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/mohamedhabibwork/laravel-multi-wallet/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/703c045d2a624a522168c7240626dbfb9e6e80bb77321124b9df3be0de71b520/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d6f68616d65646861626962776f726b2f6c61726176656c2d6d756c74692d77616c6c65742f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/mohamedhabibwork/laravel-multi-wallet/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/238d24c82e46f9832ffb778e425e9d3baae1b130dbb5ea7e5658db89607ff01a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6f68616d65646861626962776f726b2f6c61726176656c2d6d756c74692d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hwallet/laravel-multi-wallet)

A comprehensive Laravel package for managing multi-currency wallets with advanced features including multiple balance types, transfers, fees, discounts, and configurable exchange rates. Perfect for e-commerce, fintech, and any application requiring robust financial transaction management.

**🚀 Production-Ready Package** with 270+ passing tests, PHPStan level 8 compliance, and optimized `DB::transaction` usage for enterprise-grade performance and reliability.

✨ Key Features
--------------

[](#-key-features)

- 🏦 **Multi-Currency Support**: Manage wallets for various currencies with configurable exchange rates
- 💰 **Multiple Balance Types**: Support for Available, Pending, Frozen, and Trial balances
- 🔄 **Advanced Transfers**: Transfer between wallets with fees, discounts, and status tracking
- 🎯 **Polymorphic Relations**: Flexible model associations - attach wallets to any model
- 📊 **Transaction Tracking**: Comprehensive transaction history with metadata support
- ⚙️ **Configurable Architecture**: Runtime configuration with extensible interfaces
- 🔒 **Type Safety**: Built with PHP 8.1+ features and strict typing
- 🧪 **Fully Tested**: 100% test coverage with 270+ passing tests using Pest framework
- 📝 **Event System**: Rich event system for wallet operations
- 🎨 **Clean Architecture**: SOLID principles with repository and service patterns
- 🏷️ **PHP Attributes**: Easy configuration using PHP 8.1+ attributes
- ⚡ **Bulk Operations**: High-performance bulk transaction processing with `DB::transaction`
- 🗃️ **Database Agnostic**: Compatible with MySQL, PostgreSQL, SQLite, and SQL Server
- 🎛️ **Operation Validation**: Attribute-based operation validation and logging
- 🔄 **Enhanced Events**: Comprehensive event system for all operations
- 📈 **Wallet Statistics**: Built-in analytics and reconciliation tools
- 🚀 **Production Ready**: PHPStan level 8 compliance and enterprise-grade features
- 🔧 **Clean Code**: Laravel Pint formatted with PSR standards
- 🛠️ **Helper Functions**: Rich set of global helper functions for common operations
- 🔍 **Debugging Tools**: Comprehensive debugging and monitoring utilities
- 📊 **Analytics**: Built-in performance metrics and reporting
- 🔐 **Type Safety**: Strict type checking with value objects and validation

📚 Documentation
---------------

[](#-documentation)

Comprehensive documentation is available in the `/docs` directory:

- **[📖 Getting Started](docs/getting-started.md)** - Installation and basic setup
- **[🚀 Advanced Features](docs/advanced-features.md)** - Bulk operations, events, and more
- **[📋 API Reference](docs/api-reference.md)** - Complete method documentation
- **[⚙️ Configuration](docs/configuration.md)** - Detailed configuration options
- **[💡 Examples](docs/examples.md)** - Real-world usage examples
- **[✅ Best Practices](docs/best-practices.md)** - Production tips and recommendations
- **[❓ FAQ](docs/faq.md)** - Frequently asked questions

📋 Requirements
--------------

[](#-requirements)

- PHP 8.1+
- Laravel 10.0+

🚀 Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require hwallet/laravel-multi-wallet
```

Publish and run the migrations:

```
php artisan vendor:publish --provider="HWallet\LaravelMultiWallet\LaravelMultiWalletServiceProvider" --tag="migrations"
php artisan migrate
```

Optionally, publish the configuration file:

```
php artisan vendor:publish --provider="HWallet\LaravelMultiWallet\LaravelMultiWalletServiceProvider" --tag="config"
```

🎯 Quick Start
-------------

[](#-quick-start)

### 1. Add the HasWallets trait to your model

[](#1-add-the-haswallets-trait-to-your-model)

```
use HWallet\LaravelMultiWallet\Traits\HasWallets;

class User extends Authenticatable
{
    use HasWallets;

    // ... your model code
}
```

### 2. Enhanced Configuration with PHP Attributes

[](#2-enhanced-configuration-with-php-attributes)

You can now use PHP attributes to configure wallet behavior directly on your models:

```
use HWallet\LaravelMultiWallet\Attributes\WalletConfiguration;
use HWallet\LaravelMultiWallet\Traits\HasWallets;

#[WalletConfiguration(
    defaultCurrency: 'USD',
    allowedCurrencies: ['USD', 'EUR', 'GBP'],
    autoCreateWallet: true,
    walletName: 'Primary Wallet',
    enableEvents: true,
    enableAuditLog: true,
    transactionLimits: ['min_amount' => 0.01, 'max_amount' => 10000.00],
    walletLimits: ['max_balance' => 100000.00],
    enableBulkOperations: true,
    uniquenessEnabled: true,
    exchangeRateConfig: ['provider' => 'default'],
    webhookSettings: ['url' => 'https://api.example.com/webhook'],
    notificationSettings: ['email' => true, 'sms' => false],
    securitySettings: ['require_2fa' => false, 'auto_freeze_suspicious' => true]
)]
class User extends Authenticatable
{
    use HasWallets;

    // ... your model code
}
```

### 3. Create and manage wallets

[](#3-create-and-manage-wallets)

```
$user = User::find(1);

// Create a basic wallet
$wallet = $user->createWallet('USD', 'Main Wallet');

// Create with metadata
$wallet = $user->createWallet('EUR', 'European Wallet', [
    'description' => 'For European transactions',
    'meta' => ['region' => 'EU', 'priority' => 'high']
]);

// Credit the wallet
$transaction = $wallet->credit(100.00, 'available', [
    'description' => 'Initial deposit',
    'reference' => 'DEP-001'
]);

// Check balance
echo $wallet->getBalance('available'); // 100.00
```

### 4. Transfer between users

[](#4-transfer-between-users)

```
$sender = User::find(1);
$recipient = User::find(2);

// Simple transfer
$transfer = $sender->transferTo($recipient, 50.00, 'USD');

// Transfer with fee and metadata
$transfer = $sender->transferTo($recipient, 100.00, 'USD', [
    'fee' => 2.50,
    'description' => 'Payment for services',
    'reference' => 'TXN-12345'
]);

echo $transfer->getNetAmount(); // 102.50 (amount + fee)
echo $transfer->status->value; // 'confirmed'
```

🛠️ Helper Functions
-------------------

[](#️-helper-functions)

The package provides a comprehensive set of global helper functions for common wallet operations:

### Currency and Amount Formatting

[](#currency-and-amount-formatting)

```
// Format amounts with currency symbols
echo wallet_format_amount(1234.56, 'USD'); // $1,234.56
echo wallet_format_amount(1234.56, 'EUR'); // €1,234.56
echo wallet_format_amount(1234.56, 'GBP'); // £1,234.56

// Check currency support
if (wallet_is_currency_supported('USD')) {
    echo "USD is supported";
}

// Validate amounts within limits
if (wallet_validate_amount(100, 50, 200)) {
    echo "Amount is within limits";
}

// Calculate fees
$fee = wallet_calculate_fee(1000, 2.5); // 2.5% fee = 25.0
$fee = wallet_calculate_fee(1000, 0, 5.0); // Fixed fee = 5.0
$fee = wallet_calculate_fee(1000, 1.5, 2.0); // Both = 17.0

// Round amounts
$rounded = wallet_round_amount(123.456789, 2); // 123.46

// Calculate percentages
$result = wallet_calculate_percentage(1000, 15); // 150.0
```

### Wallet Operations

[](#wallet-operations)

```
// Format balance summary
$formatted = wallet_format_balance_summary($wallet);
// Returns: ['available' => '$1,000.00', 'pending' => '$0.00', ...]

// Get user wallet summary
$summary = wallet_get_user_summary($user);
// Returns: ['wallets' => [...], 'total_balance' => 1500.0, 'currencies' => ['USD', 'EUR']]
```

### Advanced Helper Class Methods

[](#advanced-helper-class-methods)

```
use HWallet\LaravelMultiWallet\Helpers\WalletHelpers;

$helpers = app(WalletHelpers::class);

// Validate currency codes
$helpers->isValidCurrency('USD'); // true
$helpers->isValidCurrency('INVALID'); // false

// Get currency symbols
$helpers->getCurrencySymbol('USD'); // $
$helpers->getCurrencySymbol('EUR'); // €

// Calculate transaction fees with strategies
$fee = $helpers->calculateTransactionFee(1000, 'percentage', 2.5); // 25.0
$fee = $helpers->calculateTransactionFee(1000, 'fixed', 10.0); // 10.0

// Tiered fee calculation
$fee = $helpers->calculateTransactionFee(1000, 'tiered', [
    'tiers' => [
        ['min' => 0, 'max' => 500, 'rate' => 1.0],
        ['min' => 500, 'max' => 1000, 'rate' => 2.0],
        ['min' => 1000, 'max' => null, 'rate' => 3.0]
    ]
]); // 30.0

// Validate metadata
$helpers->validateMetadata(['purpose' => 'savings']); // true
$helpers->validateMetadata(['password' => 'secret']); // false

// Calculate balance statistics
$stats = $helpers->calculateBalanceStatistics([$wallet1, $wallet2]);
// Returns: ['total' => 1500.0, 'average' => 750.0, 'min' => 500.0, 'max' => 1000.0]

// Handle precision calculations
$sum = $helpers->addAmounts(0.1, 0.2); // 0.3 (properly handled)

// Format multiple currencies
$formatted = $helpers->formatMultipleCurrencies([
    ['amount' => 100, 'currency' => 'USD'],
    ['amount' => 200, 'currency' => 'EUR']
]);
// Returns: ['$100.00', '€200.00']
```

🔍 Debugging and Monitoring Utilities
------------------------------------

[](#-debugging-and-monitoring-utilities)

The package includes comprehensive debugging and monitoring tools:

### Wallet Debugging

[](#wallet-debugging)

```
use HWallet\LaravelMultiWallet\Utils\WalletUtils;

// Debug wallet state
$debug = WalletUtils::debugWallet($wallet);
// Returns detailed wallet information including balances, transactions, metadata

// Validate wallet integrity
$validation = WalletUtils::validateWalletIntegrity($wallet);
// Returns: ['valid' => true, 'issues' => [], 'warnings' => []]

// Reconcile wallet balances
$result = WalletUtils::reconcileWallet($wallet);
// Returns: ['reconciled' => true, 'changes' => [...], 'summary' => '...']

// Get audit trail
$trail = WalletUtils::getWalletAuditTrail($wallet, 50);
// Returns collection of transactions and transfers with metadata

// Export wallet data
$export = WalletUtils::exportWalletData($wallet);
// Returns comprehensive wallet data for backup/analysis
```

### Performance Monitoring

[](#performance-monitoring)

```
// Get performance metrics
$metrics = WalletUtils::getWalletPerformanceMetrics($wallet);
// Returns: ['transaction_count' => 150, 'average_transaction_amount' => 75.5, ...]

// Get wallet statistics
$stats = WalletUtils::getWalletStats($wallet);
// Returns: ['total_transactions' => 100, 'total_credits' => 50, ...]

// Analyze transaction patterns
$patterns = WalletUtils::analyzeTransactionPatterns($wallet, 30);
// Returns: ['transaction_frequency' => 2.5, 'amount_patterns' => [...], ...]

// Detect anomalies
$anomalies = WalletUtils::detectAnomalies($wallet);
// Returns: ['detected' => true, 'anomalies' => [...], 'score' => 20]
```

### Health Monitoring

[](#health-monitoring)

```
// Check wallet health
$health = WalletUtils::checkWalletHealth($wallet);
// Returns: ['healthy' => true, 'score' => 85, 'issues' => [], 'recommendations' => []]

// Monitor activity
$monitoring = WalletUtils::monitorWalletActivity($wallet);
// Returns: ['activity_level' => 'medium', 'risk_score' => 25, ...]

// Generate alerts
$alerts = WalletUtils::generateAlerts($wallet);
// Returns: ['alerts' => [...], 'severity' => 'low', 'recommendations' => [...]]
```

### Bulk Operations and Maintenance

[](#bulk-operations-and-maintenance)

```
// Perform bulk operations
$result = WalletUtils::bulkOperation([$wallet1, $wallet2], 'credit', ['amount' => 100]);
// Returns: ['successful' => 2, 'failed' => 0, 'errors' => []]

// Clean up old data
$cleanup = WalletUtils::cleanupOldData($wallet, ['days' => 90]);
// Returns: ['cleaned' => true, 'removed_count' => 150, 'size_freed' => 153600]

// Optimize wallet performance
$optimization = WalletUtils::optimizeWallet($wallet);
// Returns: ['optimized' => true, 'improvements' => [...], 'performance_gain' => '15%']

// Validate data integrity
$integrity = WalletUtils::validateDataIntegrity($wallet);
// Returns: ['valid' => true, 'checksums' => [...], 'consistency' => 'good']
```

🔐 Type Safety System
--------------------

[](#-type-safety-system)

The package includes a comprehensive type safety system with value objects and strict validation:

### Type Creation and Validation

[](#type-creation-and-validation)

```
use HWallet\LaravelMultiWallet\Types\WalletTypes;

// Create type-safe amounts
$amount = WalletTypes::createAmount(100.50);
echo $amount->getValue(); // 100.50
echo $amount->isPositive(); // true

// Amount arithmetic
$sum = $amount->add(WalletTypes::createAmount(50.00)); // 150.50
$difference = $amount->subtract(WalletTypes::createAmount(25.00)); // 75.50
$product = $amount->multiply(2); // 201.00
$quotient = $amount->divide(2); // 50.25

// Currency validation
$currency = WalletTypes::createCurrency('USD');
echo $currency->getCode(); // USD
echo $currency->__toString(); // USD

// ID validation
$walletId = WalletTypes::createWalletId(123);
$transactionId = WalletTypes::createTransactionId(456);
$transferId = WalletTypes::createTransferId(789);

// Metadata with sanitization
$metadata = WalletTypes::createWalletMetadata([
    'purpose' => 'savings',
    'password' => 'secret123' // This will be sanitized out
]);

// Balance summaries
$summary = WalletTypes::createBalanceSummary([
    'available' => 1000.00,
    'pending' => 50.00,
    'frozen' => 0.00,
    'trial' => 25.00,
    'total' => 1075.00
]);

// Configuration objects
$config = WalletTypes::createWalletConfiguration([
    'default_currency' => 'USD',
    'allowed_currencies' => ['USD', 'EUR', 'GBP'],
    'transaction_limits' => ['min_amount' => 0.01, 'max_amount' => 10000.00]
]);
```

### Type Comparisons and Operations

[](#type-comparisons-and-operations)

```
// Amount comparisons
$amount1 = WalletTypes::createAmount(100.00);
$amount2 = WalletTypes::createAmount(50.00);

$amount1->greaterThan($amount2); // true
$amount2->lessThan($amount1); // true
$amount1->equals(WalletTypes::createAmount(100.00)); // true

// Currency comparisons
$usd1 = WalletTypes::createCurrency('USD');
$usd2 = WalletTypes::createCurrency('USD');
$eur = WalletTypes::createCurrency('EUR');

$usd1->equals($usd2); // true
$usd1->equals($eur); // false

// ID comparisons
$id1 = WalletTypes::createWalletId(123);
$id2 = WalletTypes::createWalletId(123);
$id3 = WalletTypes::createWalletId(456);

$id1->equals($id2); // true
$id1->equals($id3); // false
```

📊 Reporting and Analytics
-------------------------

[](#-reporting-and-analytics)

Generate comprehensive reports for analysis and auditing:

```
// Generate summary report
$report = WalletUtils::generateSummaryReport($user);
// Returns: ['user_info' => [...], 'wallet_summary' => [...], 'balance_summary' => [...]]

// Generate detailed report
$report = WalletUtils::generateDetailedReport($user, [
    'include_transactions' => true,
    'include_transfers' => true
]);
// Returns: ['user_info' => [...], 'wallets' => [...], 'transactions' => [...]]

// Generate audit report
$report = WalletUtils::generateAuditReport($user, ['days' => 30]);
// Returns: ['period' => [...], 'audit_trail' => [...], 'summary' => [...]]

// Generate performance report
$report = WalletUtils::generatePerformanceReport($user);
// Returns: ['performance_metrics' => [...], 'recommendations' => [...]]
```

🚀 High-Performance Bulk Operations with Transaction Safety
----------------------------------------------------------

[](#-high-performance-bulk-operations-with-transaction-safety)

The package provides enterprise-grade bulk operations optimized for production environments with `DB::transaction` support for data integrity:

### Bulk Credit Operations

[](#bulk-credit-operations)

```
use HWallet\LaravelMultiWallet\Services\BulkWalletManager;

$bulkManager = app(BulkWalletManager::class);

// Bulk credit multiple wallets
$operations = [
    ['wallet_id' => 1, 'amount' => 100.00, 'balance_type' => 'available', 'meta' => ['ref' => 'BULK-001']],
    ['wallet_id' => 2, 'amount' => 200.00, 'balance_type' => 'available', 'meta' => ['ref' => 'BULK-002']],
    ['wallet_id' => 3, 'amount' => 150.00, 'balance_type' => 'pending', 'meta' => ['ref' => 'BULK-003']],
];

$result = $bulkManager->bulkCredit($operations);

// Check results
if ($result['success']) {
    echo "Successfully processed {$result['successful_operations']} operations";
} else {
    echo "Failed operations: {$result['failed_operations']}";
    foreach ($result['errors'] as $error) {
        echo "Error at index {$error['index']}: {$error['error']}";
    }
}
```

### Bulk Debit Operations

[](#bulk-debit-operations)

```
// Bulk debit with validation
$operations = [
    ['wallet_id' => 1, 'amount' => 50.00, 'balance_type' => 'available'],
    ['wallet_id' => 2, 'amount' => 75.00, 'balance_type' => 'available'],
];

$result = $bulkManager->bulkDebit($operations);

// The system automatically validates sufficient funds
// and rolls back all operations if any fail
```

### Bulk Transfer Operations

[](#bulk-transfer-operations)

```
// Bulk transfers between wallets
$operations = [
    [
        'from_wallet_id' => 1,
        'to_wallet_id' => 4,
        'amount' => 100.00,
        'options' => ['fee' => 2.00, 'description' => 'Bulk transfer 1']
    ],
    [
        'from_wallet_id' => 2,
        'to_wallet_id' => 5,
        'amount' => 150.00,
        'options' => ['fee' => 3.00, 'description' => 'Bulk transfer 2']
    ],
];

$result = $bulkManager->bulkTransfer($operations);
```

### Using Bulk Operations via Traits

[](#using-bulk-operations-via-traits)

You can also use bulk operations directly through the HasWallets trait:

```
$user = User::find(1);

// Bulk credit user's wallets
$operations = [
    ['currency' => 'USD', 'amount' => 100.00],
    ['currency' => 'EUR', 'amount' => 200.00],
];

$result = $user->bulkCreditWallets($operations);

// Bulk debit operations
$result = $user->bulkDebitWallets($operations);

// Bulk freeze operations
$freezeOperations = [
    ['currency' => 'USD', 'amount' => 50.00, 'description' => 'Security freeze'],
    ['currency' => 'EUR', 'amount' => 75.00, 'description' => 'Risk assessment'],
];

$result = $user->bulkFreezeWallets($freezeOperations);

// Bulk unfreeze operations
$result = $user->bulkUnfreezeWallets($freezeOperations);
```

### Enterprise Bulk Operation Features

[](#enterprise-bulk-operation-features)

- **🔒 Transaction Safety**: All bulk operations use `DB::transaction` for ACID compliance
- **⚡ High Performance**: Optimized for processing thousands of operations efficiently
- **🔍 Validation**: Each operation is validated before execution with detailed error reporting
- **📊 Error Handling**: Comprehensive error reporting with operation-level failures
- **📡 Event Support**: Rich event system for monitoring and auditing
- **🔄 Rollback Support**: Automatic rollback on failure (all-or-nothing mode)
- **🎯 Partial Success**: Optional partial success mode for fault tolerance
- **📈 Batch Processing**: Configurable batch sizes for memory optimization
- **🧪 Fully Tested**: 100% test coverage for all bulk operations

📖 Comprehensive Guide
---------------------

[](#-comprehensive-guide)

### Balance Types

[](#balance-types)

The package supports four distinct balance types for advanced financial management:

```
$wallet = $user->createWallet('USD', 'Main Wallet');

// Available Balance - Ready for use
$wallet->credit(1000.00, 'available');
echo $wallet->getBalance('available'); // 1000.00

// Pending Balance - Funds awaiting confirmation
$wallet->moveToPending(200.00, 'Processing payment');
$wallet->confirmPending(200.00, 'Payment confirmed');

// Frozen Balance - Temporarily locked funds
$wallet->freeze(100.00, 'Security review');
$wallet->unfreeze(100.00, 'Review completed');

// Trial Balance - Promotional or test credits
$wallet->addTrialBalance(50.00, 'Welcome bonus');
$wallet->convertTrialToAvailable(25.00, 'Trial period ended');

// Get comprehensive balance summary
$summary = $wallet->getBalanceSummary();
/*
[
    'available' => 825.00,
    'pending' => 0.00,
    'frozen' => 0.00,
    'trial' => 25.00,
    'total' => 850.00
]
*/
```

### Advanced Transfer Operations

[](#advanced-transfer-operations)

```
use HWallet\LaravelMultiWallet\Services\WalletManager;

$manager = app(WalletManager::class);
$fromWallet = $user1->getWallet('USD', 'Main');
$toWallet = $user2->getWallet('USD', 'Savings');

// Transfer with fee and discount
$transfer = $manager->transfer($fromWallet, $toWallet, 100.00, [
    'fee' => 5.00,        // Service fee
    'discount' => 2.00,   // Loyalty discount
    'description' => 'Discounted transfer',
    'meta' => ['promo_code' => 'SAVE20']
]);

// Check transfer details
echo $transfer->getGrossAmount();      // 100.00 (original amount)
echo $transfer->getFee();              // 5.00
echo $transfer->getDiscount();         // 2.00
echo $transfer->getNetAmount();        // 103.00 (100 + 5 - 2)
echo $transfer->getTransferredAmount(); // 100.00 (amount received)

// Transfer status management
$transfer->markAsPending();
$transfer->markAsConfirmed();
$transfer->markAsRejected();
```

### Working with Multiple Currencies

[](#working-with-multiple-currencies)

```
// Configure exchange rates in config/multi-wallet.php
$user->createWallet('USD', 'US Dollar Wallet');
$user->createWallet('EUR', 'Euro Wallet');
$user->createWallet('GBP', 'British Pound Wallet');

// Get wallets by currency
$usdWallet = $user->getWallet('USD');
$eurWallet = $user->getWallet('EUR');

// Get all wallets
$allWallets = $user->wallets;

// Get wallets by currency
$usdWallets = $user->getWalletsByCurrency('USD');

// Check total balance across all currencies
$totalUsd = $user->getTotalBalance('USD');
$totalEur = $user->getTotalBalance('EUR');
```

### Event System

[](#event-system)

The package dispatches events for all major operations:

```
use HWallet\LaravelMultiWallet\Events\WalletCreated;
use HWallet\LaravelMultiWallet\Events\TransactionCreated;
use HWallet\LaravelMultiWallet\Events\TransferCompleted;

// Listen to wallet events
Event::listen(WalletCreated::class, function ($event) {
    Log::info('New wallet created', [
        'wallet_id' => $event->wallet->id,
        'holder' => $event->wallet->holder_type,
        'currency' => $event->wallet->currency
    ]);
});

Event::listen(TransferCompleted::class, function ($event) {
    // Send notification, update analytics, etc.
    Notification::send($event->transfer->to, new TransferReceived($event->transfer));
});
```

### Enhanced Event System

[](#enhanced-event-system)

The package includes a comprehensive event system for all wallet operations:

#### Available Events

[](#available-events)

- **Wallet Events**: `WalletCreated`, `WalletUpdated`, `WalletDeleted`, `WalletFrozen`, `WalletUnfrozen`
- **Transaction Events**: `TransactionCreated`, `TransactionConfirmed`, `TransactionFailed`, `TransactionReversed`
- **Transfer Events**: `TransferInitiated`, `TransferCompleted`, `TransferFailed`, `TransferRejected`
- **Balance Events**: `WalletBalanceChanged`, `WalletLimitExceeded`, `WalletReconciled`
- **Operation Events**: `WalletOperationStarted`, `WalletOperationCompleted`, `WalletOperationFailed`
- **Bulk Events**: `BulkOperationStarted`, `BulkOperationCompleted`, `BulkOperationFailed`
- **Configuration Events**: `WalletConfigurationChanged`, `ExchangeRateUpdated`
- **Security Events**: `SuspiciousActivityDetected`

#### Event Usage Examples

[](#event-usage-examples)

```
use HWallet\LaravelMultiWallet\Events\WalletBalanceChanged;
use HWallet\LaravelMultiWallet\Events\TransactionCreated;
use HWallet\LaravelMultiWallet\Events\SuspiciousActivityDetected;
use HWallet\LaravelMultiWallet\Events\BulkOperationStarted;
use HWallet\LaravelMultiWallet\Events\BulkOperationCompleted;
use HWallet\LaravelMultiWallet\Events\BulkOperationFailed;

// Listen for balance changes
Event::listen(WalletBalanceChanged::class, function ($event) {
    // Send notification to user
    $user = $event->wallet->holder;
    Mail::to($user)->send(new BalanceChangedNotification($event));
});

// Monitor transaction creation
Event::listen(TransactionCreated::class, function ($event) {
    // Log transaction for audit
    AuditLog::create([
        'action' => 'transaction_created',
        'wallet_id' => $event->transaction->wallet_id,
        'amount' => $event->transaction->amount,
        'type' => $event->transaction->type->value,
    ]);
});

// Handle suspicious activity
Event::listen(SuspiciousActivityDetected::class, function ($event) {
    // Freeze wallet and notify security team
    $event->wallet->freeze($event->wallet->getBalance('available'), 'Suspicious activity detected');
    SecurityTeam::notify($event);
});

// Monitor bulk operations
Event::listen(BulkOperationStarted::class, function ($event) {
    Log::info("Bulk operation started: {$event->operationType} with {$event->operationCount} operations");
});

Event::listen(BulkOperationCompleted::class, function ($event) {
    Log::info("Bulk operation completed: {$event->operationType} with {$event->successfulOperations} successful operations");
});

Event::listen(BulkOperationFailed::class, function ($event) {
    Log::error("Bulk operation failed: {$event->operationType} with {$event->failedOperations} failures");
});
```

### Using the Facade

[](#using-the-facade)

```
use HWallet\LaravelMultiWallet\Facades\LaravelMultiWallet;

// Create wallet via facade
$wallet = LaravelMultiWallet::createWallet($user, 'USD', 'Main Wallet');

// Transfer between wallets
$transfer = LaravelMultiWallet::transfer($fromWallet, $toWallet, 100.00, [
    'description' => 'Facade transfer'
]);

// Get balance summary
$summary = LaravelMultiWallet::getBalanceSummary($user, 'USD');
```

### Custom Exchange Rate Providers

[](#custom-exchange-rate-providers)

Implement your own exchange rate logic:

```
use HWallet\LaravelMultiWallet\Contracts\ExchangeRateProviderInterface;

class ApiExchangeRateProvider implements ExchangeRateProviderInterface
{
    public function getRate(string $from, string $to): float
    {
        // Fetch from external API (e.g., CurrencyLayer, Fixer.io)
        $response = Http::get("https://api.exchangerate-api.com/v4/latest/{$from}");
        return $response->json()['rates'][$to] ?? 1.0;
    }

    public function convert(float $amount, string $from, string $to): float
    {
        return $amount * $this->getRate($from, $to);
    }

    public function getSupportedCurrencies(): array
    {
        return ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD'];
    }
}

// Register in service provider
$this->app->singleton(ExchangeRateProviderInterface::class, ApiExchangeRateProvider::class);
```

📊 Wallet Statistics and Analytics
---------------------------------

[](#-wallet-statistics-and-analytics)

The package provides built-in analytics and reconciliation tools:

### Wallet Statistics

[](#wallet-statistics)

```
use HWallet\LaravelMultiWallet\Services\WalletManager;

$walletManager = app(WalletManager::class);
$wallet = $user->getWallet('USD');

// Get comprehensive wallet statistics
$stats = $walletManager->getWalletStatistics($wallet);

/*
Returns:
[
    'total_transactions' => 45,
    'total_credits' => 5000.00,
    'total_debits' => 2500.00,
    'total_transfers_sent' => 10,
    'total_transfers_received' => 8,
    'current_balance' => 2500.00,
    'available_balance' => 2000.00,
    'pending_balance' => 300.00,
    'frozen_balance' => 100.00,
    'trial_balance' => 100.00,
]
*/
```

### Wallet Reconciliation

[](#wallet-reconciliation)

```
// Check wallet balance integrity
$reconciliation = $walletManager->reconcileWallet($wallet);

if (!$reconciliation['is_balanced']) {
    // Handle discrepancies
    foreach ($reconciliation['differences'] as $balanceType => $difference) {
        Log::warning("Balance discrepancy in {$balanceType}: {$difference['difference']}");
    }

    // Auto-fix if needed
    $walletManager->autoReconcileWallet($wallet);
}
```

### User Balance Summary

[](#user-balance-summary)

```
// Get balance summary across all currencies
$summary = $walletManager->getBalanceSummary($user);

/*
Returns:
[
    [
        'currency' => 'USD',
        'total_wallets' => 3,
        'total_balance' => 5000.00,
        'available_balance' => 4500.00,
        'pending_balance' => 300.00,
        'frozen_balance' => 100.00,
        'trial_balance' => 100.00,
    ],
    [
        'currency' => 'EUR',
        'total_wallets' => 2,
        'total_balance' => 3000.00,
        // ...
    ]
]
*/
```

🗃️ Database Compatibility
-------------------------

[](#️-database-compatibility)

The package is designed to work seamlessly with all major database systems:

### Supported Databases

[](#supported-databases)

- **MySQL**: Full support with optimized foreign keys and JSON columns
- **PostgreSQL**: Native JSON support and advanced indexing
- **SQLite**: Compatible with text-based JSON storage for testing
- **SQL Server**: Full compatibility with proper data type handling

### Migration Features

[](#migration-features)

The migration files automatically detect your database type and apply appropriate optimizations:

```
// Automatic JSON column handling
if (config('database.default') === 'sqlite') {
    $table->text('meta')->nullable();  // SQLite compatibility
} else {
    $table->json('meta')->nullable();  // Native JSON for others
}

// Optimal decimal precision for all databases
$table->decimal('balance_available', 20, 8)->default(0);

// Timezone-aware timestamps where supported
if (config('database.default') === 'sqlite') {
    $table->timestamp('created_at')->useCurrent();
} else {
    $table->timestampTz('created_at')->useCurrent();
}
```

### Configuration for Different Databases

[](#configuration-for-different-databases)

```
// config/database.php

// MySQL configuration
'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'wallet_app'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'options' => [
        PDO::ATTR_EMULATE_PREPARES => false,
        PDO::ATTR_STRINGIFY_FETCHES => false,
    ],
],

// PostgreSQL configuration
'pgsql' => [
    'driver' => 'pgsql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE', 'wallet_app'),
    'username' => env('DB_USERNAME', 'postgres'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
    'prefix' => '',
    'schema' => 'public',
],

// SQLite configuration (for testing)
'sqlite' => [
    'driver' => 'sqlite',
    'database' => database_path('wallet_app.sqlite'),
    'prefix' => '',
],
```

🎛️ Advanced Features
--------------------

[](#️-advanced-features)

### Attribute-Based Operation Validation

[](#attribute-based-operation-validation)

The package uses PHP attributes to provide operation-level validation and logging:

```
use HWallet\LaravelMultiWallet\Attributes\WalletOperation;
use HWallet\LaravelMultiWallet\Attributes\BulkOperation;

class CustomWalletService
{
    #[WalletOperation(
        operation: 'custom_credit',
        description: 'Custom credit operation with validation',
        requiresValidation: true,
        logTransaction: true,
        fireEvents: true,
        auditLog: true
    )]
    public function customCredit(Wallet $wallet, float $amount): Transaction
    {
        // Custom validation logic
        if ($amount > 10000) {
            throw new \InvalidArgumentException('Amount exceeds maximum limit');
        }

        return $wallet->credit($amount, 'available', [
            'operation' => 'custom_credit',
            'validated_by' => auth()->id(),
        ]);
    }

    #[BulkOperation(
        operation: 'bulk_custom_credit',
        batchSize: 50,
        useTransaction: true,
        validateBeforeExecute: true,
        enableRollback: true
    )]
    public function bulkCustomCredit(array $operations): array
    {
        // Bulk operation with custom logic
        return $this->processBulkOperations($operations);
    }
}
```

### Multi-Model Wallet Support

[](#multi-model-wallet-support)

The package supports wallets for any model type:

```
// User wallets
class User extends Model
{
    use HasWallets;
}

// Company wallets
#[WalletConfiguration(
    defaultCurrency: 'USD',
    allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY'],
    walletLimits: ['max_balance' => 1000000.00],
    enableBulkOperations: true
)]
class Company extends Model
{
    use HasWallets;
}

// Product escrow wallets
#[WalletConfiguration(
    defaultCurrency: 'USD',
    autoCreateWallet: true,
    walletName: 'Escrow',
    transactionLimits: ['max_amount' => 50000.00]
)]
class Product extends Model
{
    use HasWallets;
}

// Usage examples
$user = User::find(1);
$company = Company::find(1);
$product = Product::find(1);

// All models can use the same wallet operations
$userWallet = $user->createWallet('USD');
$companyWallet = $company->createWallet('USD');
$escrowWallet = $product->autoCreateWallet(); // Auto-creates based on configuration

// Transfer between different model types
$user->transferTo($company, 1000.00, 'USD', ['description' => 'Service payment']);
$company->transferTo($product, 500.00, 'USD', ['description' => 'Escrow deposit']);
```

🔧 Complete WalletConfiguration API Reference
--------------------------------------------

[](#-complete-walletconfiguration-api-reference)

The enhanced WalletConfiguration system provides comprehensive control over wallet behavior through PHP attributes and programmatic configuration.

### Configuration Methods Reference

[](#configuration-methods-reference)

```