Laravel Credits

https://github.com/climactic/laravel-credits
Admin
A ledger-based Laravel package for managing credit-based systems including virtual currencies,...
Tokens:38,864
Snippets:313
Trust Score:8.2
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Installs the package via Composer. This is the first step after adding the package to your project.

```bash
composer require climactic/laravel-credits
```

--------------------------------

### whereMetadata() usage examples

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Shows three usage examples: two-parameter shorthand, three-parameter with operator, and nested key with dot notation.

```php
$user->credits()->whereMetadata('source', 'purchase')->get(); // 2-param
$user->credits()->whereMetadata('order_value', '>', 100)->get(); // 3-param
$user->credits()->whereMetadata('user.id', 123)->get(); // nested (dot notation)
```

--------------------------------

### Example - Two-parameter syntax with limit

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Example usage of creditsByMetadata with the two-parameter syntax, querying credits where metadata 'source' equals 'purchase'. The limit parameter is set to 20 using a named argument; no ordering is specified so it defaults to 'desc'.

```php
// Where metadata 'source' = 'purchase'
$purchases = $user->creditsByMetadata('source', 'purchase', limit: 20);
```

--------------------------------

### Example listener for CreditsAdded event

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Events.md

Example listener that logs when credits are added. Uses Event::listen with a closure that receives the CreditsAdded event and accesses its properties.

```php
use Climactic\Credits\Events\CreditsAdded;

Event::listen(function (CreditsAdded $event) {
 // $event->creditable, $event->transactionId, $event->amount,
 // $event->newBalance, $event->description, $event->metadata
 Log::info("Credits added", [
 'user' => $event->creditable->getKey(),
 'amount' => $event->amount,
 'new_balance' => $event->newBalance,
 ]);
});
```

--------------------------------

### Example - Three-parameter operator syntax with ordering

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Example using the three-parameter operator syntax to filter credits where metadata 'order_value' is greater than or equal to 100 acidash 10 records, ordered ascending. Use named argument 'limit' and positional 'asc' as the order.

```php
$highValue = $user->creditsByMetadata('order_value', '>=', 100, limit: 10, 'asc');
```

--------------------------------

### CreditsTransferred example listener

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Events.md

Example listener for the CreditsTransferred event. Logs the transfer activity with the amount and sender/recipient keys.

```php
use Climactic\Credits\Events\CreditsTransferred;

Event::listen(function (CreditsTransferred $event) {
 activity()->log("{$event->amount} credits transferred from
 {$event->sender->getKey()} to {$event->recipient->getKey()}");
});
```

--------------------------------

### orWhereMetadataHas() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of chaining whereMetadata and orWhereMetadataHas to filter credits by metadata presence.

```php
$user->credits()
 ->whereMetadata('source', 'purchase')
 ->orWhereMetadataHas('refund_id')
 ->get();
```

--------------------------------

### orWhereMetadata() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of chaining whereMetadata and orWhereMetadata to filter credits by multiple metadata sources.

```php
$user->credits()
 ->whereMetadata('source', 'purchase')
 ->orWhereMetadata('source', 'refund')
 ->get();
```

--------------------------------

### orWhereMetadataLength() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of chaining whereMetadataLength and orWhereMetadataLength to filter credits by metadata array length.

```php
$user->credits()
 ->whereMetadataLength('tags', '>', 1)
 ->orWhereMetadataLength('tags', '=', 0)
 ->get();
```

--------------------------------

### CreditsDeducted example listener

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Events.md

Example listener for the CreditsDeducted event. Sends a payment confirmation email to the creditable model's email address.

```php
use Climactic\Credits\Events\CreditsDeducted;

Event::listen(function (CreditsDeducted $event) {
 Mail::to($event->creditable->email)->send(
 new PaymentConfirmation($event->amount, $event->newBalance)
 );
});
```

--------------------------------

### orWhereMetadataNull() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of chaining whereMetadataHas and orWhereMetadataNull to filter credits by metadata nullability.

```php
$user->credits()
 ->whereMetadataHas('order_id')
 ->orWhereMetadataNull('tags')
 ->get();
```

--------------------------------

### creditable() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of using the creditable() relationship to retrieve the owner of a credit transaction.

```php
$credit = Credit::find(1);
$owner = $credit->creditable; // eager-loaded via morphTo
echo get_class($owner); // App\Models\User
```

--------------------------------

### orWhereMetadataContains() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Example of chaining whereMetadataContains and orWhereMetadataContains to filter credits by metadata tags.

```php
$user->credits()
 ->whereMetadataContains('tags', 'premium')
 ->orWhereMetadataContains('tags', 'featured')
 ->get();
```

--------------------------------

### Using hasCredits() in a condition

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Example usage of hasCredits(). Checks if the user has at least 30.00 credits before proceeding with a purchase. Note the extra closing parentheses in the example, which may be a syntax error.

```php
if ($user->hasCredits(30.00)))) {
 // Proceed with the purchase
}
```

--------------------------------

### $metadata shape example for credit operations

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/types.md

Example of the `$metadata` argument accepted by `creditAdd()`, `creditDeduct()`, `creditTransfer()`, and deprecated variants. Stored verbatim into the `metadata` JSON column; keys are free-form and queried via dot notation. Content is not validated by the package.

```php
$metadata = [
 'order_id' => 123,
 'product' => 'Premium Subscription',
 'user_id' => 456,
 'tags' => ['premium', 'featured'],
];
```

--------------------------------

### Example output message for InsufficientCreditsException

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/InsufficientCreditsException.md

Shows the exact output message when a debit of 50.0 is attempted against a balance of 30.0.

```text
Insufficient credits. Requested: 50, Available: 30
```

--------------------------------

### Basic creditDeduct example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Basic usage of creditDeduct: finds a user, deducts 50.00 credits with an optional description, and displays the updated running balance.

```php
$user = User::find(1);

$debit = $user->creditDeduct(50.00, 'Purchase Made');

echo $debit->running_balance; // previous balance minus 50

```

--------------------------------

### Selecting metadata indexes for common queries

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Examples of Laravel credit queries using whereMetadata and whereMetadataContains to illustrate which metadata indexes to create. Each query includes a comment indicating the index name or database-specific handling.

```php
// If you often query by source
$user->credits()->whereMetadata('source', 'purchase')->get();
// → Index: metadata_source

// If you filter by order_id
$user->credits()->whereMetadata('order_id', 12345)->get();
// → Index: metadata_order_id

// If you query by tags array
$user->credits()->whereMetadataContains('tags', 'premium')->get();
// → MySQL: Index on virtual column for tags
// → PostgreSQL: GIN index handles this automatically
```

--------------------------------

### Observing Deprecations

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/errors.md

Example of setting a custom error handler to log E_USER_DEPRECATED warnings.

```APIDOC
## Observing Deprecations

### Description
Set a custom error handler to log deprecation warnings triggered by deprecated methods.

### Code Example
php
set_error_handler(function ($errno, $errstr) {
    if ($errno === E_USER_DEPRECATED) {
        Log::debug('Deprecated call', ['message' => $errstr]);
    }
    return false; // keep default PHP handling
});

```

--------------------------------

### Handle deprecation warnings from deprecated credit methods

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Use this example to capture and log deprecation warnings when calling deprecated methods like addCredits() during testing. The error handler observes E_USER_DEPRECATED and logs the message, then calls the deprecated method which triggers the warning. This helps identify deprecated usage before upgrading to v2.0.

```php
// Register an error handler if you need to observe deprecations during testing
set_error_handler(function ($errno, $errstr) {
 if ($errno === E_USER_DEPRECATED) {
 Log::debug('Deprecated call', ['message' => $errstr]);
 }
 return false;
});

$amount = $user->addCredits(50.00); // triggers E_USER_DEPRECATED, returns Credit
```

--------------------------------

### whereMetadataNull() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Filters credits that do not have a 'tags' metadata key or where it is null.

```php
$withoutTags = $user->credits()->whereMetadataNull('tags')->get();
```

--------------------------------

### creditBalanceAt

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Gets the balance at a specific time.

```APIDOC
## creditBalanceAt(Carbon|DateTimeInterface|int $dateTime)

### Description
Gets the balance at a specific time.

### Method
creditBalanceAt

### Parameters
- **$dateTime** (Carbon|DateTimeInterface|int) - Required - The date/time to check the balance at.

### Returns
- The balance at the given time.
```

--------------------------------

### creditBalance

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Gets the current balance of the model.

```APIDOC
## creditBalance()

### Description
Gets the current balance of the model.

### Method
creditBalance

### Parameters
None.

### Returns
- The current balance as a float.
```

--------------------------------

### creditHistory

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Gets the transaction history.

```APIDOC
## creditHistory(int $limit = 10, string $order = 'desc')

### Description
Gets the transaction history for the model.

### Method
creditHistory

### Parameters
- **$limit** (int) - Optional - The number of transactions to return. Defaults to 10.
- **$order** (string) - Optional - The sort order, either 'asc' or 'desc'. Defaults to 'desc'.

### Returns
- A collection of credit transactions.
```

--------------------------------

### Retrieve Historical Balance at a Given Date

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Get the balance as of a specific date by passing a DateTime instance to creditBalanceAt.

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

```

--------------------------------

### Message format for InsufficientCreditsException

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/InsufficientCreditsException.md

Builds the exception message using sprintf with %s placeholders, without numeric formatting. For example, a failed creditDeduct(50.0) against a balance of 30.0 produces 'Insufficient credits. Requested: 50, Available: 30'.

```php
parent::__construct(sprintf(
 'Insufficient credits. Requested: %s, Available: %s',
 $requested,
 $available
))
```

--------------------------------

### creditsByMetadata

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Gets credits filtered by metadata key/value.

```APIDOC
## creditsByMetadata(string $key, $operator, $value = null, int $limit = 10, string $order = 'desc')

### Description
Gets credits filtered by metadata key/value.

### Method
creditsByMetadata

### Parameters
- **$key** (string) - Required - The metadata key to filter by.
- **$operator** - Required - The comparison operator.
- **$value** - Optional - The value to compare against.
- **$limit** (int) - Optional - The number of results to return. Defaults to 10.
- **$order** (string) - Optional - The sort order. Defaults to 'desc'.

### Returns
- A collection of credit transactions.
```

--------------------------------

### creditHistoryWithMetadata

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Gets credits filtered by multiple metadata.

```APIDOC
## creditHistoryWithMetadata(array $filters, int $limit = 10, string $order = 'desc')

### Description
Gets credits filtered by multiple metadata.

### Method
creditHistoryWithMetadata

### Parameters
- **$filters** (array) - Required - An array of metadata filters.
- **$limit** (int) - Optional - The number of results to return. Defaults to 10.
- **$order** (string) - Optional - The sort order. Defaults to 'desc'.

### Returns
- A collection of credit transactions.
```

--------------------------------

### creditTransfer() error handling and self-transfer

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Error handling and self-transfer example. Catches InsufficientCreditsException when the sender lacks creditscompile, and shows that transferring to the same model is supported, writing both debit and credit rows without changing the net balance.

```php
try {
 $result = $sender->creditTransfer($recipient, 100.00));
} catch (\Climactic\Credits\Exceptions\InsufficientCreditsException $e) {
 // Sender balance too low for the transfer
 Log::warning('Transfer failed', ['sender' => $sender->id, 'amount' => 100]);
}

// Self-transfer (sender === recipient) is supported: locks are acquired in deterministic order once per model
$selfResult = $user->creditTransfer($user, 50.00);
// A debit row and a credit row are both written for the same model; net balance is unchanged .
```

--------------------------------

### whereMetadataContains() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Filters credits where the metadata 'tags' array contains the value 'premium'.

```php
$premium = $user->credits()->whereMetadataContains('tags', 'premium')->get();
```

--------------------------------

### whereMetadataLength() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Filters credits where the 'tags' array has a length greater than 1.

```php
$multipleTags = $user->credits()->whereMetadataLength('tags', '>', 1)->get();
```

--------------------------------

### whereMetadataHas() usage example

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Filters credits that have an 'order_id' metadata key.

```php
$withOrderId = $user->credits()->whereMetadataHas('order_id')->get();
```

--------------------------------

### Publish and Run Migrations

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Publishes the migration files and then runs them to create the necessary database tables. Use the 'credits-migrations' tag.

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

--------------------------------

### configurePackage() method body

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/CreditsServiceProvider.md

Declares the package name, config file, and migration. The config file is registered under the 'credits' key, and the migration stub is published to database/migrations/.

```php
$package
 ->name('laravel-credits')
 ->hasConfigFile()
 ->hasMigration('create_credits_table');
```

--------------------------------

### Publish Config File

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Optionally publishes the configuration file. Use the 'credits-config' tag.

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

--------------------------------

### Publishing migration and config via artisan

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/CreditsServiceProvider.md

Commands to publish the migration stub and run it, then optionally publish the config file for customization. After publishing, customize the allow_negative_balance and table_name keys.

```bash
# Publish the migration stub, then run it
php artisan vendor:publish --tag="credits-migrations"
php artisan migrate

# Optional: publish the config file for customization
php artisan vendor:publish --tag="credits-config"
```

--------------------------------

### Run tests with Composer

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Executes the package test suite using Composer. Run this command from the project root to verify the package works correctly.

```bash
composer test
```

--------------------------------

### Configuration File

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Configuration options: 'allow_negative_balance' (default false) and 'table_name' (default 'credits'). Adjust the table name if you've modified the migration.

```php
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',
];
```

--------------------------------

### Metadata queries with null, has, and length methods

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Demonstrates null checks and the 'has' and 'length' metadata methods. Uses two-parameter where shorthand for simple equality, and three-parameter syntax for explicit null checks. Orders by 'asc' with a limit of 10.

```php
$nullChecks = $user->creditHistoryWithMetadata([
 ['key' => 'refund_id', 'operator' => '=', 'value' => null], // where metadata refund_id IS NULL
 ['key' => 'status', 'value' => 'pending'], // simple equality (two-parameter)
 ['key' => 'tags', 'method' => 'has'], // where metadata tags IS NOT NULL
 ['key' => 'items', 'method' => 'length', 'operator' => '>', 'value' => 1],
], limit: 10, 'asc');
```

--------------------------------

### configurePackage() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/CreditsServiceProvider.md

The single lifecycle hook implemented by the provider. spatie/laravel-package-tools calls it during package discovery to declare artifacts.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### Shipped config file config/credits.php

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/CreditsServiceProvider.md

The exact file registered by the provider. Contains allow_negative_balance (default false) and table_name (default 'credits'). When allow_negative_balance is false, deducting more than available throws InsufficientCreditsException.

```php
<?php

return [
 /*
 |--------------------------------------------------------------------------
 | Allow Negative Balance
 |--------------------------------------------------------------------------
 |
 | When set to true, accounts can have negative balances. When false,
 | attempting to deduct more credits than available will throw an
 | InsufficientCreditsException.
 |
 */
 'allow_negative_balance' => false,

 /*
 |--------------------------------------------------------------------------
 | Database Table Name
 |--------------------------------------------------------------------------
 |
 | The name of the table used to store credit transactions
 | Default is 'credits'.
 |
 */
 'table_name' => 'credits',
];
```

--------------------------------

### Add credit with description and check balance

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Creates a credit transaction with a description and outputs the updated running balance and type. The amount must be greater than 0, otherwise an \InvalidArgumentException is thrown.

```php
$user = User::find(1);

$credit = $user->creditAdd(100.00, 'Subscription Activated');

echo $credit->running_balance; // 100.00
echo $credit->type; // 'credit'
```

--------------------------------

### Perform Basic Credit Operations on a User

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Perform common credit operations: adding, deducting, checking balance, and verifying sufficient credits before a transaction.

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

```

--------------------------------

### Checking sufficiency before creditDeduct

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Recommended pattern: checks sufficiency via hasCredits before deducting, then handles InsufficientCreditsException that may still occur under concurrency. Logs a warning if the balance drops below zero.

```php
if (! $user->hasCredits(30.00)))) {
 // Insufficient abort before attempting the deduction
 return redirect()->back()->withErrors(['credits' => 'Not enough credits']);
}

try {
 $user->creditDeduct(30.00, 'Feature unlock');
} catch (\Climactic\Credits\Exceptions\InsufficientCreditsException $e) {
 // Also possible under concurrency; the negative-balance guard rejected the debit
 Log::warning('Balance dropped below zero', ['user' => $user->id, 'e' => $e]);
}

```

--------------------------------

### creditBalance() basic usage

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Basic usage of HasCredits::creditBalance(), retrieving the balance and comparing it to a threshold. The method returns 0.0 when no transactions exist.

```php
$balance = $user->creditBalance();

if ($balance >= 100) {
 // proceed
}
```

--------------------------------

### Filter credits by metadata with creditsByMetadata and creditHistoryWithMetadata

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Shows how to filter credit history by metadata using the creditsByMetadata and creditHistoryWithMetadata methods. The note explains that creditHistoryWithMetadata distinguishes two-parameter and three-parameter syntax based on the presence of the 'value' key, allowing null value checks.

```php
// 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 (explicitly include 'value' key)
$nullChecks = $user->creditHistoryWithMetadata([
    ['key' => 'refund_id', 'operator' => '=', 'value' => null],  // Check for null
    ['key' => 'status', 'value' => 'pending'],                   // Simple equality
], limit: 10);
```

--------------------------------

### Use Advanced Metadata Query Scopes

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Advanced metadata queries: contains, existence, null checks, and array-length comparisons.

```php
// Check if metadata array contains a value
$premium = $user->credits()
    ->whereMetadataContains('tags', 'premium')
    ->get();

// Check if metadata key exists
$withOrderId = $user->credits()
    ->whereMetadataHas('order_id')
    ->get();

// Check if metadata key is null or doesn't exist
$withoutTags = $user->credits()
    ->whereMetadataNull('tags')
    ->get();

// Query by metadata array length
$multipleTags = $user->credits()
    ->whereMetadataLength('tags', '>', 1)
    ->get();

```

--------------------------------

### Fetch Transaction History with creditHistory

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Retrieve transaction history with configurable count and order (defaults to 10 entries in descending order; pass 20 and 'asc' for a different result).

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

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

```

--------------------------------

### CreditsAdded constructor with promoted properties

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Events.md

Constructor signature for the CreditsAdded event, using PHP 8 promoted properties. Properties are read-only and set at construction time.

```php
public function __construct(
 public Model $creditable,
 public int $transactionId,
 public float $amount,
 public float $newBalance,
 public ?string $description,
 public array $metadata
) {}
```

--------------------------------

### Query credit history with multiple metadata filters

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Returns credits filtered by multiple metadata conditions combined with AND. Filters missing a 'key' are skipped. The $limit is clamped to 1..1000 and invalid $order falls back to 'desc'. Throws InvalidArgumentException for invalid metadata keys.

```php
public function creditHistoryWithMetadata(array $filters, int $limit = 10, string $order = 'desc'): EloquentCollection
```

```php
$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);
```

--------------------------------

### Basic use of credits() relation

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Shows basic usage of the credits() relation: retrieve all Credit records ordered by insertion, or count them. Assumes a User model instance with the HasCredits trait.

```php
$user = User::find(1);

// All credits for the user, ordered by insertion
$transactions = $user->credits()->orderByDesc('id')->get();

// Count
$count = $user->credits()->count();
```

--------------------------------

### Deprecated Methods Overview

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

A table of deprecated methods with their signatures, replacements, and source lines.

```APIDOC
## Deprecated Methods

All of the following still function (they delegate to their replacements) but raise an `E_USER_DEPRECATED` warning via `trigger_error()`. They are scheduled for removal **in v2.0**.

| Deprecated method | Signature | Replacement | Source line |
|--------------------|-----------|-------------|-------------|
| `addCredits()` | `addCredits(float $amount, ?string $description = null, array $metadata = []): Credit` | `creditAdd()` | `src/Traits/HasCredits.php:87` |
| `deductCredits()` | `deductCredits(float $amount, ?string $description = null, array $metadata = []): Credit` | `creditDeduct()` | `src/Traits/HasCredits.php:149` |
| `getCurrentBalance()` | `getCurrentBalance(): float` | `creditBalance()` | `src/Traits/HasCredits.php:174` |
| `transferCredits()` | `transferCredits(self $recipient, float $amount, ?string $description = null, array $metadata = []): array` | `creditTransfer()` | `src/Traits/HasCredits.php:249` |
| `getTransactionHistory()` | `getTransactionHistory(int $limit = 10, string $order = 'desc'): EloquentCollection` | `creditHistory()` | `src/Traits/HasCredits.php:294` |
| `hasEnoughCredits()` | `hasEnoughCredits(float $amount): bool` | `hasCredits()` | `src/Traits/HasCredits.php:314` |
| `getBalanceAsOf()` | `getBalanceAsOf($dateTime): float` | `creditBalanceAt()` | `src/Traits/HasCredits.php:354` |
| `creditTransactions()` | `creditTransactions(): MorphMany` | `credits()` | `src/Traits/HasCredits.php:30` |

### Example - Handling deprecation signals

```php
// Register an error handler if you need to observe deprecations during testing
set_error_handler(function ($errno, $errstr) {
 if ($errno === E_USER_DEPRECATED) {
 Log::debug('Deprecated call', ['message' => $errstr]);
 }
 return false;
});

$amount = $user->addCredits(50.00); // triggers E_USER_DEPRECATED, returns Credit
```
```

--------------------------------

### Model configuration for Credit model

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Protected properties on the Credit model: $fillable and $casts. The $casts array casts amount and running_balance to decimal:2 and metadata to array.

```php
protected $fillable = [
 'amount',
 'description',
 'type',
 'metadata',
 'running_balance',
 'creditable_type',
 'creditable_id',
];

protected $casts = [
 'amount' => 'decimal:2',
 'running_balance' => 'decimal:2',
 'metadata' => 'array',
];
```

--------------------------------

### creditsByMetadata() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Signature of the creditsByMetadata method. Call it on a User model to retrieve credits matching a metadata key/value. Use the two-parameter syntax ('key', 'value') or three-parameter with an operator. The limit is clamped between 1 and 1000; invalid order values fall back to 'desc'.

```php
public function creditsByMetadata(string $key, $operator = null, $value = null, int $limit = 10, string $order = 'desc'): EloquentCollection
```

--------------------------------

### creditDeduct() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Defines the creditDeduct method signature. It requires a positive float amount; optional description and metadata are accepted. The method returns a Credit instance or throws exceptions for invalid amounts or insufficient balance.

```php
public function creditDeduct(float $amount, ?string $description = null, array $metadata = []): Credit

```

--------------------------------

### Constructor signature for InsufficientCreditsException

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/InsufficientCreditsException.md

Defines the constructor that takes the requested and available amounts as floats. The parent Exception constructor receives only the message; code and previous are left at defaults (code = 0).

```php
public function __construct(float $requested, float $available)
```

--------------------------------

### Chaining metadata scopes on credits()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Chains metadata scopes and amount filtering on the credits() relation to retrieve matching Credit records. Uses whereMetadata('source', 'purchase') and a where clause on amount greater than 50.

```php
$purchases = $user->credits()
 ->whereMetadata('source', 'purchase')
 ->where('amount', '>', 50)
 ->get();
```

--------------------------------

### Create GIN indexes on JSONB metadata for PostgreSQL

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Laravel migration that creates GIN indexes on the credits table's JSONB metadata column for PostgreSQL. The up method creates a GIN index for all JSON operators and optional path-specific indexes, while down removes all three indexes. Uses the configured table name from 'credits.table_name'.

```php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;

return new class extends Migration
{
    public function up()
    {
        $tableName = config('credits.table_name', 'credits');

        // GIN index supports all JSON operators (@>, ?, ?&, ?|, etc.)
        DB::statement("
            CREATE INDEX {$tableName}_metadata_gin_idx
            ON {$tableName} USING GIN (metadata)
        ");

        // Optional: Add specific path indexes for even faster queries
        DB::statement("
            CREATE INDEX {$tableName}_metadata_source_idx
            ON {$tableName} ((metadata->>'source'))
        ");

        DB::statement("
            CREATE INDEX {$tableName}_metadata_order_id_idx
            ON {$tableName} ((metadata->'order_id'))
        ");
    }

    public function down()
    {
        $tableName = config('credits.table_name', 'credits');

        DB::statement("DROP INDEX IF EXISTS {$tableName}_metadata_gin_idx");
        DB::statement("DROP INDEX IF EXISTS {$tableName}_metadata_source_idx");
        DB::statement("DROP INDEX IF EXISTS {$tableName}_metadata_order_id_idx");
    }
};
```

--------------------------------

### Transfer Credits Between Models with creditTransfer

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Transfer credits from one model instance to another.

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

```

--------------------------------

### Catch InsufficientCreditsException when deducting credits

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/errors.md

Use this when calling creditDeduct() with an amount that might exceed the available balance. The exception is thrown when the running balance would go negative and config('credits.allow_negative_balance') is falsy (default). Catch it to handle the failure gracefully; the exception message includes requested and available amounts, the enclosing DB transaction rolls back, and no debit is persisted.

```PHP
use Climactic\Credits\Exceptions\InsufficientCreditsException;

try {
 $user->creditDeduct(50.00, 'Purchase');
} catch (InsufficientCreditsException $e) {
 // Message already includes requested and available amounts
 Log::warning($e->getMessage());
 return back()->with('error', 'Not enough credits');
}
```

--------------------------------

### composer.json provider declaration for auto-discovery

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/CreditsServiceProvider.md

Declares the service provider under extra.laravel.providers so Laravel auto-discovers it. No manual registration is needed when this is present.

```json
"extra": {
 "laravel": {
 "providers": [
 "Climactic\\Credits\\CreditsServiceProvider"
 ]
 }
}
```

--------------------------------

### Add credit with metadata and handle invalid amount

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Adds a credit with metadata and catches the exception thrown when the amount is not greater than 0. The error message is "Amount must be greater than 0.".

```php
try {
 $user->creditAdd(100.00, 'Purchase', [
 'order_id' => 123,
 'product' => 'Premium Subscription',
 'tags' => ['premium', 'featured'],
 ]);
} catch (\InvalidArgumentException $e) {
 // Amount was <= 0
 report($e->getMessage()); // "Amount must be greater than 0."
}
```

--------------------------------

### Pre-check pattern with hasCredits()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/InsufficientCreditsException.md

Shows a non-atomic guard using hasCredits() before deducting. Note that this is not atomic under concurrency; catching the exception is still recommended for strict guarantees.

```php
if ($user->hasCredits(50.00))) {
 $user->creditDeduct(50.00); // happy path; no exception expected
} else {
 // Abort early with a friendly error
 return back()->withErrors(['credits' => 'Insufficient balance']);
}
```

--------------------------------

### Basic use of creditBalanceAt() with DateTime and integer timestamps

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Basic usage: pass a DateTime object or integer timestamps. Integers > 9999999999 are treated as milliseconds and converted, smaller as seconds. Returns a float balance or 0.0 if no transactions exist.

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

$sinceEpoch = $user->creditBalanceAt(1700000000)); // seconds
$msTimestamp = $user->creditBalanceAt(1700000000123); // milliseconds auto-converted
```

--------------------------------

### creditAdd(float $amount, ?string $description = null, array $metadata = []): Credit

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Creates a credit (positive) transaction for the model, updates its running balance, and dispatches a CreditsAdded event after the database commit. The amount must be greater than 0, otherwise an InvalidArgumentException is thrown.

```APIDOC
## creditAdd(float $amount, ?string $description = null, array $metadata = []): Credit

### Description
Creates a credit (positive) transaction for the model, updates its running balance, and dispatches a `CreditsAdded` event after the database commit (the event implements `ShouldDispatchAfterCommit`).

### Method
creditAdd

### Signature
```php
public function creditAdd(float $amount, ?string $description = null, array $metadata = []): Credit
```

### Parameters
- `$amount` (float) - Required - Amount to add; must be greater than 0.
- `$description` (?string) - Optional - Optional human-readable description stored on the transaction. Default: `null`.
- `$metadata` (array) - Optional - Optional arbitrary metadata stored with the transaction (cast to JSON). Default: `[]`.

### Returns
- `Climactic\Credits\Models\Credit` - The created `Credit` record with the **updated** `running_balance`.

### Throws
- `\InvalidArgumentException` - If `$amount <= 0`, message: `Amount must be greater than 0.`
- `Throwable` (propagated) - Database failure; the transaction is retried up to 5 times on deadlock/transient errors first.

### Example - Basic use
```php
$user = User::find(1);

$credit = $user->creditAdd(100.00, 'Subscription Activated');

echo $credit->running_balance; // 100.00
echo $credit->type; // 'credit'
```

### Example - With metadata and validation error handling
```php
try {
    $user->creditAdd(100.00, 'Purchase', [
        'order_id' => 123,
        'product' => 'Premium Subscription',
        'tags' => ['premium', 'featured'],
    ]);
} catch (\InvalidArgumentException $e) {
    // Amount was <= 0
    report($e->getMessage()); // "Amount must be greater than 0."
}
```
```

--------------------------------

### Credit constructor signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Constructor signature for the Credit model, overriding Eloquent's constructor to bind the table name from configuration.

```php
public function __construct(array $attributes = [])
```

--------------------------------

### creditDeduct(float $amount, ?string $description = null, array $metadata = []): Credit

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Creates a debit (negative) transaction for the model, updates its running balance, and dispatches a CreditsDeducted event after the database commit. If negative balances are disallowed and the resulting balance would drop below zero, an InsufficientCreditsException is thrown and the transaction is rolled back.

```APIDOC
## creditDeduct(float $amount, ?string $description = null, array $metadata = []): Credit

### Description
Creates a debit (negative) transaction for the model, updates its running balance, and dispatches a `CreditsDeducted` event after the database commit. If negative balances are disallowed (`config('credits.allow_negative_balance') === false`, the default) and the resulting balance would drop below zero, an `InsufficientCreditsException` is thrown and the transaction is rolled back.

### Signature
```php
public function creditDeduct(float $amount, ?string $description = null, array $metadata = []): Credit
```

### Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `$amount` | `float` | | Amount to deduct; must be greater than 0 |
| `$description` | `?string` | `null` | Optional description for the transaction. |
| `$metadata` | `array` | `[]` | Optional metadata attached to the transaction. |

### Returns
| Type | Description |
|------|-------------|
| `Climactic\Credits\Models\Credit` | The created `Credit` record representing the debit, with the resulting `running_balance`. |

### Throws
| Error | Condition |
|-------|-----------|
| `\InvalidArgumentException` | `$amount <= 0` `Amount must be greater than 0.` |
| `Climactic\Credits\Exceptions\InsufficientCreditsException` | `allow_negative_balance` is falsy and `newBalance < 0`. Message: `Insufficient credits. Requested: %s, Available: %s`. |

### Example - Basic use
```php
$user = User::find(1);

$debit = $user->creditDeduct(50.00, 'Purchase Made');

echo $debit->running_balance; // previous balance minus 50
```

### Example - Checking sufficiency first (recommended pattern)
```php
if (! $user->hasCredits(30.00)))) {
 // Insufficient abort before attempting the deduction
 return redirect()->back()->withErrors(['credits' => 'Not enough credits']);
}

try {
 $user->creditDeduct(30.00, 'Feature unlock');
} catch (\Climactic\Credits\Exceptions\InsufficientCreditsException $e) {
 // Also possible under concurrency; the negative-balance guard rejected the debit
 Log::warning('Balance dropped below zero', ['user' => $user->id, 'e' => $e]);
}
```

Source: `src/Traits/HasCredits.php:105`
```

--------------------------------

### whereMetadataNull()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Filters credits where the metadata key is null or does not exist.

```APIDOC
## whereMetadataNull()

### Description
Filters credits where the metadata key is null or does not exist.

### Method
Eloquent Query Scope

### Signature
```php
public function scopeWhereMetadataNull(
 \Illuminate\Database\Eloquent\Builder $query,
 string $key
): \Illuminate\Database\Eloquent\Builder
```

### Parameters
- `$query` (\Illuminate\Database\Eloquent\Builder) - Required - Eloquent query builder.
- `$key` (string) - Required - Metadata key (dot notation supported).

### Builds
`$query->whereNull("metadata->{$key}")`

### Example
```php
$withoutTags = $user->credits()->whereMetadataNull('tags')->get();
```

### Source
`src/Models/Credit.php:142`
```

--------------------------------

### Chain Multiple Metadata Conditions

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Combine multiple metadata conditions and a raw amount condition in a single query.

```php
$filtered = $user->credits()
    ->whereMetadata('source', 'purchase')
    ->whereMetadata('category', 'electronics')
    ->whereMetadataContains('tags', 'featured')
    ->where('amount', '>', 50)
    ->get();

```

--------------------------------

### Sanitization behavior of creditHistory()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Demonstrates sanitization behavior: when the limit exceeds 1000, it is clamped to 1000, and an invalid order value falls back to 'desc'. The count of the returned collection is therefore at most 1000.

```php
$history = $user->creditHistory(5000, 'sideways'); // limit clamps to 1000, order falls back to 'desc'
echo $history->count(); // <= 1000
```

--------------------------------

### Add Credits with Metadata

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Attach metadata (including nested arrays) to a credit transaction by passing an associative array as the third argument to creditAdd.

```php
$metadata = [
    'order_id' => 123,
    'product' => 'Premium Subscription',
    'user_id' => 456,
    'tags' => ['premium', 'featured']
];

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

```

--------------------------------

### Model annotations for Credit model

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

PHPDoc annotations describing the properties of the Credit model, including id, amount, description, type, metadata, running_balance, creditable_type, creditable_id, timestamps, and the creditable relation.

```php
/**
 * @property int|string $id
 * @property float $amount
 * @property string|null $description
 * @property string $type
 * @property array<string, mixed>|null $metadata
 * @property float $running_balance
 * @property string $creditable_type
 * @property int|string $creditable_id
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 * @property-read \Illuminate\Database\Eloquent\Model $creditable
 */
```

--------------------------------

### creditHistory() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Method signature for creditHistory(). Use it to retrieve recent credit transactions for a model. Results are ordered by created_at then id (tie-break) according to the specified direction. The $order parameter is normalized to 'asc'/'desc' (invalid values fall back to 'desc') and the $limit is clamped to range 1..1000.

```php
public function creditHistory(int $limit = 10, string $order = 'desc'): EloquentCollection
```

--------------------------------

### Credit constructor behavior

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Behavior of the Credit constructor: calls parent constructor and sets the table name from the 'credits.table_name' config, defaulting to 'credits'.

```php
parent::__construct($attributes);
$this->setTable(config('credits.table_name', 'credits'));
```

--------------------------------

### Define credits() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Declares the credits() method signature that defines a morph-many Eloquent relationship to Credit records. Returns an Illuminate\Database\Eloquent\Relations\MorphMany relation for the 'creditable' morph.

```php
public function credits(): MorphMany
```

--------------------------------

### creditBalance() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Signature of the HasCredits::creditBalance() method, which returns the current credit balance as a float. Use this to check the model's available credits.

```php
public function creditBalance(): float
```

--------------------------------

### creditBalance()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Retrieves the model's current credit balance by reading the most recent running_balance across all transactions. Returns 0.0 when no transactions exist.

```APIDOC
## creditBalance()

### Description
Retrieves the model's current credit balance the most recent `running_balance` across all transactions, ordered by `latest('id')` (ID ordering guarantees correctness even when timestamps collide). Returns `0.0` when no transactions exist.

### Signature
```php
public function creditBalance(): float
```

### Parameters
None.

### Returns
- **float** - The current credit balance.

### Example - Basic use
```php
$balance = $user->creditBalance();

if ($balance >= 100) {
    // proceed
}
```

### Source
`src/Traits/HasCredits.php:161`
```

--------------------------------

### creditBalanceAt() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Signature of the creditBalanceAt method: accepts a DateTimeInterface or integer Unix timestamp (seconds or milliseconds, auto-detected), returns the running balance as a float at or before the given time, or 0.0 if no transactions exist.

```php
public function creditBalanceAt($dateTime): float
```

--------------------------------

### Query Transactions with whereMetadata

Source: https://github.com/climactic/laravel-credits/blob/main/README.md

Query transactions by metadata values with support for comparison operators, dot-notation nesting, and raw where for deeply nested keys.

```php
// Query by simple metadata value
$purchases = $user->credits()
    ->whereMetadata('source', 'purchase')
    ->get();

// Query with comparison operators
$highValue = $user->credits()
    ->whereMetadata('order_value', '>', 100)
    ->get();

// Query by nested metadata (using dot notation)
$specificUser = $user->credits()
    ->whereMetadata('user.id', 123)
    ->get();

// Deeply nested keys (use raw where for very deep nesting)
$results = $user->credits()
    ->where('metadata->data->level1->level2->value', 'found')
    ->get();

```

--------------------------------

### hasCredits() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Method signature for hasCredits(). Checks whether the model's current balance is at least the given amount. Returns true when creditBalance() >= $amount, else false.

```php
public function hasCredits(float $amount): bool
```

--------------------------------

### Log E_USER_DEPRECATED warnings with set_error_handler

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/errors.md

Register an error handler that logs E_USER_DEPRECATED warnings, useful for observing deprecations in tests or logs. The handler returns false to keep default PHP handling.

```php
set_error_handler(function ($errno, $errstr) {
 if ($errno === E_USER_DEPRECATED) {
 Log::debug('Deprecated call', ['message' => $errstr]);
 }
 return false; // keep default PHP handling
});
```

--------------------------------

### Basic use of creditHistory()

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/HasCredits.md

Basic usage of creditHistory(). Fetches the most recent 10 transactions by default (descending order), or the 20 oldest when passing 20 and 'asc'. The user variable is retrieved with Eloquent's find method.

```php
$user = User::find(1);

$last10 = $user->creditHistory(); // 10 most recent, desc
$last20Asc = $user->creditHistory(20, 'asc'); // 20 oldest, asc
```

--------------------------------

### creditable() method signature

Source: https://github.com/climactic/laravel-credits/blob/main/_autodocs/api-reference/Credit.md

Signature for the creditable() method, which defines a polymorphic relationship to the owning model.

```php
public function creditable(): MorphTo
```
Tokens:
Raw