Money Class - Laravel Brick Money

Overview

The Money class is the core of Laravel Brick Money. It represents a monetary amount with an associated currency and provides methods for arithmetic operations, comparisons, allocation, and formatting.

Creating Money Objects

of() - Create from Amount

Creates Money from a decimal amount. By default, uses DefaultContext which scales the amount to match the currency’s default fraction digits.

use Devhammed\LaravelBrickMoney\Money;

// Basic creation
$money = Money::of('100.50', 'USD');
// Result: USD 100.50

$money = Money::of(2.5, 'USD');
// Result: USD 2.50 (auto-scaled to 2 decimal places)

$money = Money::of('1000', 'JPY');
// Result: JPY 1000 (0 decimal places for JPY)

If the amount cannot be safely converted to the currency’s scale, an exception is thrown unless you provide a custom Context and RoundingMode.

Method Signature

public static function of(
    BigNumber|float|int|string $amount,
    Currency|string $currency,
    ?Context $context = null,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

amount

BigNumber|float|int|string

required

The monetary amount (e.g., “100.50”, 100.5, 100)

currency

Currency|string

required

Currency code (e.g., “USD”) or Currency object

context

Context

default:"null"

Optional Context to control scaling behavior

roundingMode

RoundingMode

default:"UNNECESSARY"

Rounding mode if amount needs adjustment

ofMinor() - Create from Minor Units

Creates Money from minor units (cents). This is useful when working with cent-based values from databases or APIs.

// Create from cents
$money = Money::ofMinor(1234, 'USD');
// Result: USD 12.34

$money = Money::ofMinor('5000', 'EUR');
// Result: EUR 50.00

$money = Money::ofMinor(1000, 'JPY');
// Result: JPY 1000 (JPY has no minor units)

Method Signature

public static function ofMinor(
    BigNumber|float|int|string $amount,
    Currency|string $currency,
    ?Context $context = null,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

Getting Money Values

Amount Accessors

$money = Money::of('123.45', 'USD');

// Get amount as BigDecimal
$amount = $money->getAmount();
// Returns: BigDecimal(123.45)

// Get minor amount (cents)
$minorAmount = $money->getMinorAmount();
// Returns: BigDecimal(12345)

// Get unscaled amount (all digits)
$unscaled = $money->getUnscaledAmount();
// Returns: BigInteger(12345)

// Get the sign (-1, 0, or 1)
$sign = $money->getSign();
// Returns: 1

Understanding unscaled amounts

The unscaled amount represents all digits without the decimal point. For example, USD 123.4567 returns 1234567 as a BigInteger. This is useful for precise calculations without floating-point issues.

Currency and Context

$money = Money::of('100', 'USD');

// Get Currency object
$currency = $money->getCurrency();

// Get Context
$context = $money->getContext();

Arithmetic Operations

Addition

$money = Money::of('100.50', 'USD');

// Add another Money object
$result = $money->plus(Money::of('50.25', 'USD'));
// Result: USD 150.75

// Add a numeric value
$result = $money->plus('25.50');
// Result: USD 126.00

// Add with rounding
$result = $money->plus('10.999', RoundingMode::DOWN);
// Result: USD 111.49

When adding two Money objects, they must have the same currency or a MoneyMismatchException is thrown.

Method Signature

public function plus(
    Money|BigNumber|float|int|string $that,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

Subtraction

$money = Money::of('100.50', 'USD');

$result = $money->minus('50.25');
// Result: USD 50.25

$result = $money->minus(Money::of('25', 'USD'));
// Result: USD 75.50

Method Signature

public function minus(
    Money|BigNumber|float|int|string $that,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

Multiplication

$money = Money::of('10.50', 'USD');

// Multiply by integer
$result = $money->multipliedBy(3);
// Result: USD 31.50

// Multiply by decimal
$result = $money->multipliedBy('1.5');
// Result: USD 15.75

// Multiply with rounding
$result = $money->multipliedBy('1.333', RoundingMode::DOWN);
// Result: USD 13.99

Method Signature

public function multipliedBy(
    BigNumber|float|int|string $that,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

Division

$money = Money::of('100.00', 'USD');

// Simple division
$result = $money->dividedBy(4);
// Result: USD 25.00

// Division with rounding
$result = $money->dividedBy(3, RoundingMode::UP);
// Result: USD 33.34

Method Signature

public function dividedBy(
    BigNumber|float|int|string $that,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): static

Quotient and Remainder

$money = Money::of('100.00', 'USD');

// Get quotient only
$quotient = $money->quotient(3);
// Result: USD 33.33

// Get both quotient and remainder
[$quotient, $remainder] = $money->quotientAndRemainder(3);
// $quotient: USD 33.33
// $remainder: USD 0.01

Comparisons

Equality and Comparison

$money = Money::of('100.00', 'USD');

// Compare to another value (-1, 0, or 1)
$result = $money->compareTo('100.00');
// Returns: 0 (equal)

$result = $money->compareTo('50.00');
// Returns: 1 (greater than)

// Equality check
$isEqual = $money->isEqualTo(Money::of('100', 'USD'));
// Returns: true

Comparison Methods

Less Than
Greater Than
Zero Checks
Sign Checks

$money = Money::of('100', 'USD');

$money->isLessThan('150'); // true
$money->isLessThan('100'); // false

$money->isLessThanOrEqualTo('100'); // true

$money = Money::of('100', 'USD');

$money->isGreaterThan('50'); // true
$money->isGreaterThan('100'); // false

$money->isGreaterThanOrEqualTo('100'); // true

$money = Money::of('0', 'USD');

$money->isZero(); // true
$money->isPositive(); // false
$money->isNegative(); // false
$money->isPositiveOrZero(); // true
$money->isNegativeOrZero(); // true

$positive = Money::of('100', 'USD');
$negative = Money::of('-100', 'USD');

$positive->isPositive(); // true
$negative->isNegative(); // true

$positive->getSign(); // 1
$negative->getSign(); // -1

Money Allocation

Allocate by Ratios

Split money according to ratios, distributing any remainder over the first results.

$money = Money::of('49.99', 'USD');

// Allocate by ratios: 1:2:3:4
$allocated = $money->allocate(1, 2, 3, 4);
// Returns:
// [0] => USD 5.00
// [1] => USD 10.00
// [2] => USD 15.00
// [3] => USD 19.99  (gets the remainder)

Method Signature

public function allocate(int ...$ratios): array

Allocate with Remainder Separate

$money = Money::of('49.99', 'USD');

$allocated = $money->allocateWithRemainder(1, 2, 3, 4);
// Returns:
// [0] => USD 4.99
// [1] => USD 9.98
// [2] => USD 14.97
// [3] => USD 19.96
// [4] => USD 0.09  (remainder as separate item)

Split into Equal Parts

$money = Money::of('100.00', 'USD');

// Split into 3 parts
$parts = $money->split(3);
// Returns:
// [0] => USD 33.34  (gets the remainder)
// [1] => USD 33.33
// [2] => USD 33.33

Method Signature

public function split(int $parts): array

Split with Remainder Separate

$money = Money::of('100.00', 'USD');

$parts = $money->splitWithRemainder(3);
// Returns:
// [0] => USD 33.33
// [1] => USD 33.33
// [2] => USD 33.33
// [3] => USD 0.01  (remainder)

Allocation and split methods are perfect for dividing invoices, calculating commissions, or distributing amounts while maintaining penny-perfect accuracy.

Transformations

Absolute Value

$money = Money::of('-100.50', 'USD');

$absolute = $money->abs();
// Result: USD 100.50

Negation

$money = Money::of('100.50', 'USD');

$negated = $money->negated();
// Result: USD -100.50

Currency Conversion

$usd = Money::of('100.00', 'USD');

// Convert USD to EUR with exchange rate
$eur = $usd->convertedTo('EUR', '0.91', null, RoundingMode::UP);
// Result: EUR 91.00

Method Signature

public function convertedTo(
    Currency|string $currency,
    BigNumber|float|int|string $exchangeRate,
    ?Context $context = null,
    RoundingMode $roundingMode = RoundingMode::UNNECESSARY
): Money

currency

Currency|string

required

Target currency code or Currency object

exchangeRate

BigNumber|float|int|string

required

Exchange rate from source to target currency

context

Context

default:"null"

Optional Context for the resulting Money (defaults to same as original)

roundingMode

RoundingMode

default:"UNNECESSARY"

Rounding mode for conversion

Formatting

Basic Formatting

Format using the currency’s configured separators and symbol placement.

$money = Money::of('1234.56', 'USD');

echo $money->format();
// Output: $1,234.56

echo $money->format(allowWholeNumber: true);
// Output: $1,234.56 (keeps decimals since it has fractional part)

$whole = Money::of('1234', 'USD');
echo $whole->format(allowWholeNumber: true);
// Output: $1,234 (no decimals for whole numbers)

Method Signature

public function format(bool $allowWholeNumber = false): string

allowWholeNumber

bool

default:"false"

If true, omits decimal places when amount has no fractional part

Locale-Based Formatting

Format using PHP’s NumberFormatter with locale-specific rules.

$money = Money::of('1234.56', 'USD');

// Format with default locale
echo $money->formatLocale();
// Output: $1,234.56 (using default en_US)

// Format with specific locale
echo $money->formatLocale('de_DE');
// Output: 1.234,56 $ (German formatting)

echo $money->formatLocale('fr_FR');
// Output: 1 234,56 $ (French formatting)

Method Signature

public function formatLocale(
    ?string $locale = null,
    bool $allowWholeNumber = false,
    ?Closure $callback = null
): string

locale

string

default:"null"

Locale code (e.g., “en_US”, “de_DE”). Falls back to configured default.

allowWholeNumber

bool

default:"false"

If true, omits decimal places when amount has no fractional part

callback

Closure

default:"null"

Optional callback to customize the NumberFormatter instance

Custom Formatter Example

$money = Money::of('1234.56', 'USD');

echo $money->formatLocale('en_US', false, function ($formatter) {
    // Customize the NumberFormatter
    $formatter->setAttribute(NumberFormatter::MIN_FRACTION_DIGITS, 3);
    $formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 3);
});
// Output: $1,234.560

String Conversion

$money = Money::of('100.50', 'USD');

// Automatic string conversion uses format()
echo $money;
// Output: $100.50

echo (string) $money;
// Output: $100.50

Formatting methods use floating-point arithmetic internally, so discrepancies may appear with very large monetary values. For precise storage, use getMinorAmount() instead.

Global Configuration

Default Locale

use Devhammed\LaravelBrickMoney\Money;

// Set default locale
Money::locale('de_DE');

// Get current locale
$locale = Money::locale();
// Returns: "de_DE"

JSON Serialization

// Default JSON format
$money = Money::of('123.45', 'USD');
echo $money->toJson();
// Output: {"amount":"12345","value":"123.45","currency":{...}}

// Customize JSON serialization globally
Money::jsonSerializer(function ($money) {
    return [
        'amount' => (string) $money->getAmount(),
        'currency' => $money->getCurrency()->getCode(),
    ];
});

echo $money->toJson();
// Output: {"amount":"123.45","currency":"USD"}

Laravel Integration

The Money class implements Laravel contracts for seamless integration.

$money = Money::of('100.50', 'USD');

// Array conversion
$array = $money->toArray();
// Returns: ['amount' => '10050', 'value' => '100.50', 'currency' => ...]

// JSON conversion
$json = $money->toJson();

// Automatic JSON serialization
return response()->json(['price' => $money]);
// Returns: {"price":{"amount":"10050","value":"100.50","currency":{...}}}

Macros

Extend the Money class with custom methods using Laravel’s Macroable trait.

use Devhammed\LaravelBrickMoney\Money;

// Define a macro
Money::macro('addTax', function (float $taxRate) {
    return $this->multipliedBy(1 + $taxRate, RoundingMode::UP);
});

// Use the macro
$price = Money::of('100.00', 'USD');
$withTax = $price->addTax(0.08);
// Result: USD 108.00

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

​Overview

​Creating Money Objects

​of() - Create from Amount

​Method Signature

​ofMinor() - Create from Minor Units

​Method Signature

​Getting Money Values

​Amount Accessors

​Currency and Context

​Arithmetic Operations

​Addition

​Method Signature

​Subtraction

​Method Signature

​Multiplication

​Method Signature

​Division

​Method Signature

​Quotient and Remainder

​Comparisons

​Equality and Comparison

​Comparison Methods

​Money Allocation

​Allocate by Ratios

​Method Signature

​Allocate with Remainder Separate

​Split into Equal Parts

​Method Signature

​Split with Remainder Separate

​Transformations

​Absolute Value

​Negation

​Currency Conversion

​Method Signature

​Formatting

​Basic Formatting

​Method Signature

​Locale-Based Formatting

​Method Signature

​Custom Formatter Example

​String Conversion

​Global Configuration

​Default Locale

​JSON Serialization

​Laravel Integration

​Macros

​Next Steps

Currency Class

Laravel Integration

Build docs developers (and LLMs) love

Overview

Creating Money Objects

of() - Create from Amount

Method Signature

ofMinor() - Create from Minor Units

Method Signature

Getting Money Values

Amount Accessors

Currency and Context

Arithmetic Operations

Addition

Method Signature

Subtraction

Method Signature

Multiplication

Method Signature

Division

Method Signature

Quotient and Remainder

Comparisons

Equality and Comparison

Comparison Methods

Money Allocation

Allocate by Ratios

Method Signature

Allocate with Remainder Separate

Split into Equal Parts

Method Signature

Split with Remainder Separate

Transformations

Absolute Value

Negation

Currency Conversion

Method Signature

Formatting

Basic Formatting

Method Signature

Locale-Based Formatting

Method Signature

Custom Formatter Example

String Conversion

Global Configuration

Default Locale

JSON Serialization

Laravel Integration

Macros

Next Steps