Laravel Credits

Metadata queries perform full table scans by default. For large datasets (> 100k transactions), you should implement database-specific optimizations.

MySQL/MariaDB: Virtual Columns

Use virtual generated columns to extract JSON values into indexed columns.

PostgreSQL: GIN Indexes

Use a GIN (Generalized Inverted Index) on the metadata column to support all JSON operations efficiently.

SQLite

Metadata queries work but are slower on large datasets. Ensure the JSON1 extension is enabled (SQLite 3.38+).

// Example: MySQL Virtual Column Migration
return new class extends Migration
{
    public function up()
    {
        $tableName = config('credits.table_name', 'credits');

        DB::statement("ALTER TABLE {$tableName} ADD COLUMN metadata_source VARCHAR(255) GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.source'))) VIRTUAL");
        Schema::table($tableName, function (Blueprint $table) {
            $table->index('metadata_source');
        });
    }
};

For simpler workflows, use these convenience methods on the model:

• creditsByMetadata(string $key, mixed $value, int $limit = null, string $order = 'desc', string $operator = '='): A shorthand for querying and limiting metadata-filtered transactions.
• creditHistoryWithMetadata(array $filters, int $limit = null): Allows passing an array of filter definitions.

Filter Array Syntax for creditHistoryWithMetadata:

• Two-parameter style: ['key' => '...', 'value' => '...'] (uses equality).
• Three-parameter style: ['key' => '...', 'operator' => '...', 'value' => '...'] (allows custom operators like > or <).
• Null handling: To check for null, explicitly include 'value' => null in the array.

// Get credits filtered by metadata (with limit and ordering)
$purchases = $user->creditsByMetadata('source', 'purchase', limit: 20, order: 'desc');

// With comparison operators
$highValue = $user->creditsByMetadata('order_value', '>=', 100, limit: 10);

// Multiple metadata filters
$filtered = $user->creditHistoryWithMetadata([
    ['key' => 'source', 'value' => 'purchase'],
    ['key' => 'category', 'value' => 'electronics'],
    ['key' => 'tags', 'value' => 'premium', 'method' => 'contains'],
    ['key' => 'order_value', 'operator' => '>', 'value' => 50],
], limit: 25);

// Query with null values
$nullChecks = $user->creditHistoryWithMetadata([
    ['key' => 'refund_id', 'operator' => '=', 'value' => null],
    ['key' => 'status', 'value' => 'pending'],
], limit: 10);

The following methods are available on models using the Laravel Credits trait to manage balances and transactions:

• 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.
• creditsByMetadata(string $key, $operator, $value = null, int $limit = 10, string $order = 'desc'): Get credits filtered by metadata key/value.
• creditHistoryWithMetadata(array $filters, int $limit = 10, string $order = 'desc'): Get credits filtered by multiple metadata.

The HasCredits trait provides methods to manipulate a model's credit balance and check availability.

• creditAdd(float $amount, string $description, array $metadata = []): Adds credits to the balance.
• creditDeduct(float $amount, string $description): Deducts credits from the balance.
• creditBalance(): Returns the current credit balance.
• hasCredits(float $amount): Returns true if the model has enough credits for the specified amount.
• creditBalanceAt(DateTimeInterface $date): Returns the balance as it was on a specific date.

// 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
}

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