README

Laravel Credits

A ledger-based Laravel package for managing credit-based systems in your application. Perfect for virtual currencies, reward points, or any credit-based feature.

Features

🔄 Credit transactions
💸 Credit transfers
📢 Events for adding, deducting, and transferring credits
💰 Balance tracking with running balance
📊 Transaction history
🔍 Point-in-time balance lookup
📝 Transaction metadata support
⚡ Efficient queries using running balance and indexes

Installation

You can install the package via composer:

composer require climactic/laravel-credits

Publish and run the migrations:

php artisan vendor:publish --tag="credits-migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag="credits-config"

Configuration

return [
    // Allow negative balances
    'allow_negative_balance' => false,

    // Table name for credit transactions (change if you've updated the migration table name)
    'table_name' => 'credits',
];

Database Recommendations

Concurrency & Locking: This package uses row-level locking (SELECT FOR UPDATE) to prevent race conditions during concurrent credit operations. This requires a database engine that supports proper transaction isolation and row-level locking:

✅ MySQL/MariaDB: Requires InnoDB engine (default in modern versions)
✅ PostgreSQL: Full support for row-level locking
⚠️ SQLite: Row-level locking is ignored; concurrent operations may produce incorrect results in high-concurrency scenarios

For production environments with concurrent users, we recommend using MySQL/MariaDB (InnoDB) or PostgreSQL.

Usage

Setup Your Model

Add the HasCredits trait to any model that should handle credits:

use Climactic\Credits\Traits\HasCredits;

class User extends Model
{
    use HasCredits;
}

Basic Usage

// Add credits
$user->creditAdd(100.00, 'Subscription Activated');

// Deduct credits
$user->creditDeduct(50.00, 'Purchase Made');

// Get current balance
$balance = $user->creditBalance();

// Check if user has enough credits
if ($user->hasCredits(30.00)) {
    // Proceed with transaction
}

Transfers

Transfer credits between two models:

$sender->creditTransfer($recipient, 100.00, 'Paying to user for their service');

Transaction History

// Get last 10 transactions
$history = $user->creditHistory();

// Get last 20 transactions in ascending order
$history = $user->creditHistory(20, 'asc');

Historical Balance

Get balance as of a specific date:

$date = new DateTime('2023-01-01');
$balanceAsOf = $user->creditBalanceAt($date);

Metadata

Add additional information to transactions:

$metadata = [
    'order_id' => 123,
    'product' => 'Premium Subscription'
];

$user->creditAdd(100.00, 'Purchase', $metadata);

Events

Events are fired for each credit transaction, transfer, and balance update.

The events are:

CreditsAdded
CreditsDeducted
CreditsTransferred

API Reference

Available Methods

Method	Description
`creditAdd(float $amount, ?string $description = null, array $metadata = [])`	Add credits to the model
`creditDeduct(float $amount, ?string $description = null, array $metadata = [])`	Deduct credits from the model
`creditBalance()`	Get the current balance
`creditTransfer(Model $recipient, float $amount, ?string $description = null, array $metadata = [])`	Transfer credits to another model
`creditHistory(int $limit = 10, string $order = 'desc')`	Get transaction history
`hasCredits(float $amount)`	Check if model has enough credits
`creditBalanceAt(Carbon\|DateTimeInterface\|int $dateTime)`	Get balance at a specific time
`credits()`	Eloquent relationship to credit transactions

Deprecated Methods

The following methods are deprecated and will be removed in v2.0. They still work but will trigger deprecation warnings:

Deprecated Method	Use Instead
`addCredits()`	`creditAdd()`
`deductCredits()`	`creditDeduct()`
`getCurrentBalance()`	`creditBalance()`
`transferCredits()`	`creditTransfer()`
`getTransactionHistory()`	`creditHistory()`
`hasEnoughCredits()`	`hasCredits()`
`getBalanceAsOf()`	`creditBalanceAt()`
`creditTransactions()`	`credits()`

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please report security vulnerabilities to security@climactic.co.

License

The MIT License (MIT). Please see License File for more information.

Disclaimer

This package is not affiliated with Laravel. It's for Laravel but is not by Laravel. Laravel is a trademark of Taylor Otwell.

climactic / laravel-credits

Maintainers

Details