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.

Sponsors

GitHub Sponsors: @climactic

To become a title sponsor, please contact sponsors@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.