Getting Started

Minimal Steps

Installation:

composer require tomatophp/filament-wallet
php artisan filament-wallet:install

Register Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:
```
->plugin(\TomatoPHP\FilamentWallet\FilamentWalletPlugin::make())
```

Enable Wallet on Model: Add traits to your model (e.g., Account):

use Bavix\Wallet\Interfaces\Wallet;
use Bavix\Wallet\Traits\HasWalletFloat;

class Account extends Model implements Wallet
{
    use HasWalletFloat;
}

Add Wallet Action to Table:

use TomatoPHP\FilamentWallet\Filament\Actions\WalletAction;

public function table(Table $table): Table
{
    $table->actions([
        WalletAction::make('wallet'),
    ]);
}

First Use Case

Charge a user’s wallet directly from the Filament admin panel by clicking the "Wallet" action in the user table. The modal will appear, allowing you to input an amount and confirm the transaction.

Implementation Patterns

Core Workflows

Wallet Management:
- Use HasWalletFloat trait to enable wallet functionality on any model (e.g., User, Customer, Subscription).
- Leverage the WalletAction to trigger deposits/withdrawals from Filament tables.
Transaction Tracking:
- All transactions are automatically logged by bavix/laravel-wallet (underlying package).
- Access transaction history via the Transactions List page (auto-generated by the plugin).

Integration with Filament Accounts:

Publish the Filament Accounts model:

php artisan vendor:publish --tag="filament-accounts-model"

\TomatoPHP\FilamentWallet\FilamentWalletPlugin::make()->useAccounts()

Customization:
- Override default behavior by extending the FilamentWalletPlugin or WalletAction classes.
- Modify transaction notifications by publishing and customizing the notification class:
```
php artisan vendor:publish --tag="filament-wallet-notifications"
```

Best Practices

Model Design: Implement the Wallet interface and use HasWalletFloat for decimal precision (e.g., cents, crypto).
```
class User extends Authenticatable implements Wallet
{
    use HasWalletFloat;
}
```
Action Placement: Add WalletAction to relevant tables (e.g., UserResource, CustomerResource) for granular control.
```
$table->actions([
    WalletAction::make('wallet')->label('Top Up Balance'),
]);
```

Permissions: Use Filament’s built-in policies or custom gates to restrict wallet actions:

public static function getPages(): array
{
    return [
        'wallets' => fn (User $user) => $user->can('manage-wallets'),
    ];
}

Testing: Run the included test suite to validate core functionality:
```
composer test
```

Gotchas and Tips

Pitfalls

Filament Version Mismatch:
- Issue: The package requires Filament v4. Using it with v3 will cause errors (e.g., live() → lazy() changes).
- Fix: Upgrade Filament or use a compatible version of filament-wallet (e.g., v1.x).
Floating-Point Precision:
- Issue: HasWalletFloat uses floats for balance storage, which can lead to rounding errors in financial calculations.
- Fix: Use Bavix\Wallet\Traits\HasWalletInteger for integer-based currencies (e.g., cents) and handle division manually.
Transaction Notifications:
- Issue: Notifications may not trigger if the Notification facade isn’t properly configured.
- Fix: Publish the notification config:
```
php artisan vendor:publish --tag="filament-wallet-notifications"
```
Livewire Lazy Loading:
- Issue: The lazy() method may cause unexpected delays if not used correctly (e.g., blocking UI updates).
- Fix: Ensure your WalletAction is properly configured for async operations:
```
WalletAction::make('wallet')->lazy()->modalWidth('50%')
```
Database Migrations:
- Issue: The package doesn’t create migrations for the wallets table (handled by bavix/laravel-wallet).
- Fix: Run the underlying package’s migrations:
```
php artisan vendor:publish --provider="Bavix\Wallet\WalletServiceProvider" --tag="wallet-migrations"
php artisan migrate
```

Debugging Tips

Check Wallet Balance: Use Tinker to verify balances:

php artisan tinker
>> $user = App\Models\User::first();
>> $user->wallet->balance

Transaction Logs: Inspect the wallet_transactions table for discrepancies:

SELECT * FROM wallet_transactions WHERE walletable_id = {user_id} ORDER BY created_at DESC;

Filament Plugin Registration: Ensure the plugin is registered after Filament’s core resources:

->plugin(\TomatoPHP\FilamentWallet\FilamentWalletPlugin::make())
   ->navigationGroups([
       'Users' => ['wallets', 'transactions'],
   ]);

Extension Points

Custom Wallet Actions: Extend WalletAction to add pre/post-logic:

use TomatoPHP\FilamentWallet\Filament\Actions\WalletAction as BaseWalletAction;

class CustomWalletAction extends BaseWalletAction
{
    protected function handle(): void
    {
        // Custom logic before charging
        parent::handle();
        // Custom logic after charging
    }
}

Override Default Views: Publish and modify the Blade views:
```
php artisan vendor:publish --tag="filament-wallet-views"
```

Add Custom Fields: Extend the wallet model to include metadata (e.g., currency, last_updated):

class User extends Authenticatable implements Wallet
{
    use HasWalletFloat;

    protected $casts = [
        'wallet_currency' => 'string',
    ];
}

Webhook Integration: Use Laravel’s wallet:transaction event to trigger external actions:

use Bavix\Wallet\Events\TransactionCreated;

TransactionCreated::dispatch($transaction)
    ->then(fn () => $this->dispatchWebhook($transaction));

Configuration Quirks

Decimal Places: Configure the number of decimal places in config/wallet.php:
```
'decimal_places' => 2, // Default for cents
```
Default Currency: Set the default currency in the config:
```
'default_currency' => 'USD',
```

Plugin Pages: Customize the plugin’s navigation group:

FilamentWalletPlugin::make()
    ->navigationGroup('Finance')
    ->navigationIcon('heroicon-o-wallet')

Filament Wallet Laravel Package