README

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.

ayup-creative / laravel-currency-cast

Maintainers

Package info

Statistics

Security