November 3, 2025

Laravel Credits — Build Credit-Based Systems Effortlessly in Laravel

Tutorial

package

Laravel Credits — Build Credit-Based Systems Effortlessly in Laravel

When your app needs virtual currencies, reward points, or internal credit balances, ou don’t have to reinvent the wheel.

Laravel Credits gives you a clean, flexible foundation for any credit-based system right inside your Laravel application.

Built around a ledger-based model, it ensures accuracy, auditability, and extensibility — whether you're handling in-app credits, gamification points, or digital wallet balances.

Installation

Install the package via Composer:

composer require climactic/laravel-credits

Publish the migrations and migrate:

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

Optionally, publish the config file:

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

Setup

Add the HasCredits trait to any model that should have a credit balance:

use Climactic\Credits\Traits\HasCredits;

class User extends Model
{
    use HasCredits;
}

That’s it — your model now supports credit transactions.

Basic Operations

Add and deduct credits with clear transaction descriptions:

// Add credits
$user->creditAdd(100, 'Signup Bonus');

// Deduct credits
$user->creditDeduct(50, 'Purchased Premium Item');

// Check balance
$user->creditBalance(); // returns float

// Check available credits
if ($user->hasCredits(30)) {
    // proceed
}

Each operation is stored as a transaction in the database — maintaining a full history of credits added, deducted, or transferred.

Credit Transfers

Transfer credits between users or models effortlessly:

$sender->creditTransfer($receiver, 200, 'Paying for a service');

Transfers automatically generate two transactions — one debit, one credit — keeping both sides consistent.

Transaction History

Retrieve detailed credit activity for any model:

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

// Paginate or change sort order
$history = $user->creditHistory(20, 'asc');

Historical Balances

Need to see what a user’s balance was at a specific date? No problem:

$date = new DateTime('2024-01-01');
$balance = $user->creditBalanceAt($date);

This is useful for auditing, refunds, or analytics on past states.

Metadata Support

Every transaction can include rich metadata — order IDs, products, tags, anything:

$user->creditAdd(100, 'Order Purchase', [
    'order_id' => 123,
    'product' => 'Pro Plan',
    'tags' => ['upgrade', 'subscription']
]);

Querying by Metadata

You can query transactions by metadata values using clean, expressive methods:

// Find purchases
$purchases = $user->credits()->whereMetadata('source', 'purchase')->get();

// Filter by nested keys
$orders = $user->credits()->whereMetadata('order.id', 123)->get();

// Find transactions with specific tags
$premium = $user->credits()->whereMetadataContains('tags', 'premium')->get();

Performance Optimization

For high-volume apps, Laravel Credits supports efficient querying strategies:

Use running balances to reduce recalculations.
Add indexes on frequently queried metadata keys.
MySQL/MariaDB users can use virtual columns for JSON indexes.
PostgreSQL users can take advantage of GIN indexes on JSONB fields.

Events

Listen for lifecycle events to trigger logic when credits change:

CreditAdded::class
CreditDeducted::class
CreditTransferred::class

These are great for sending notifications, triggering rewards, or syncing data with other systems.

Read more & install: https://laravel-hub.com/package/laravel-credits