Laravel Currency Cast

A PHP library for handling monetary values with integer-based precision, including a Laravel custom caster for Eloquent models.

Features

  • Integer-based monetary calculations to avoid floating-point errors.
  • Automatic casting of database values to Money objects in Laravel.
  • Supports different currencies and formatting via intl.
  • Arithmetic operations (add, subtract, multiply, divide, discount, sum).
  • Comparison operations (greater than, less than, equals, etc.).
  • Livewire support via Wireable interface.
  • JSON serialization.

Installation

composer require ayup-creative/laravel-currency-cast

Usage

Money Value Object

You can create Money objects using the constructor or the fromFloat helper:

use AyupCreative\Casts\Currency\Values\Money;

// Directly from raw cents
$price = new Money(1000, 'GBP'); // £10.00

// From a float value
$price = Money::fromFloat(19.99, 'USD'); // $19.99

// Using the helper
$price = money(500); // £5.00 (defaults to GBP)

Arithmetic Operations

$m1 = money(1000); // £10.00
$m2 = money(500);  // £5.00

$sum = $m1->add($m2);        // £15.00
$diff = $m1->subtract($m2);  // £5.00
$multi = $m1->multiply(1.5); // £15.00
$div = $m1->divide(2);       // £5.00
$discounted = $m1->discount(20); // £8.00 (20% off)

Comparisons

$m1 = money(1000);
$m2 = money(2000);

$m1->isLessThan($m2); // true
$m1->isGreaterThan($m2); // false
$m1->isEqualTo(money(1000)); // true
$m1->isZero(); // false
$m1->isPositive(); // true

Formatting

$money = money(12345); // £123.45
echo $money->formatted('en_GB'); // "£123.45"
echo $money->formatted('en_US'); // "£123.45" (Currency code is respected)
echo (string) $money; // Uses default en_GB

Laravel Caster

To use the caster in your Eloquent models, add it to the $casts array:

use AyupCreative\Casts\Currency\Currency;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    protected $casts = [
        'price' => Currency::class,
    ];

    // Optional: Define currency code for the model
    public $currencyCode = 'USD';
    
    // OR use a method
    public function getCurrencyCode()
    {
        return 'EUR';
    }
}

The caster can also resolve the currency code from another attribute on the model:

class Product extends Model
{
    protected $casts = [
        'price' => Currency::class,
    ];

    // Points to the 'currency' column in the database
    public $currencyCode = 'currency';
}

If neither currencyCode property nor getCurrencyCode() method exists, the caster will look for a configuration value: config('currency.currency_code').

Testing

Run the test suite using PHPUnit:

composer test

Development

Pre-commit Hooks

This repository uses pre-commit to ensure code quality and commit message standards.

To install the hooks, run:

pre-commit install

The hooks include:

  • conventional-pre-commit: Validates commit messages follow the conventional commit standard.
  • phpunit: Runs the full test suite before each commit to ensure stability.