Money Class - Laravel Brick Money

The Money class is the primary class for working with monetary values in Laravel Brick Money. It wraps the Brick\Money\Money class and provides a fluent Laravel interface.

Class Definition

namespace Devhammed\LaravelBrickMoney;

class Money implements Arrayable, Jsonable, JsonSerializable, Stringable

The Money class uses Laravel’s Macroable trait, allowing you to extend it with custom methods.

Creating Money Instances

of()

Returns Money of the given amount and currency.By default, the money is created with a DefaultContext. This means that the amount is scaled to match the currency’s default fraction digits. For example, Money::of('2.5', 'USD') will yield USD 2.50. If the amount cannot be safely converted to this scale, an exception is thrown.To override this behaviour, a Context instance can be provided. Operations on this Money return a Money with the same context.

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

currency

Currency|string

required

The currency code (e.g., ‘USD’) or Currency instance

context

Context|null

default:"null"

Optional context for precision control

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode to use if rounding is required

return

Money

A new Money instance

Example:

use Devhammed\LaravelBrickMoney\Money;

$money = Money::of(100, 'USD'); // $100.00
$money = Money::of('2.5', 'EUR'); // €2.50

ofMinor()

Returns Money from a number of minor units (cents).By default, the money is created with a DefaultContext. This means that the amount is scaled to match the currency’s default fraction digits. For example, Money::ofMinor('1234', 'USD') will yield USD 12.34. If the amount cannot be safely converted to this scale, an exception is thrown.

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

amount

BigNumber|float|int|string

required

The amount in minor units (cents)

currency

Currency|string

required

The currency code (e.g., ‘USD’) or Currency instance

context

Context|null

default:"null"

Optional context for precision control

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode to use if rounding is required

return

Money

A new Money instance

Example:

$money = Money::ofMinor(100, 'USD'); // $1.00
$money = Money::ofMinor(1234, 'EUR'); // €12.34

ofMoney()

Create an instance of Money from Brick\Money\Money.

public static function ofMoney(BrickMoney $money): static

money

Brick\Money\Money

required

A Brick Money instance

return

Money

A new Money instance

Example:

use Brick\Money\Money as BrickMoney;

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

Configuration Methods

locale()

Get or set the locale to use for formatting.

public static function locale(?string $locale = null): string

locale

string|null

default:"null"

The locale to set (e.g., ‘en_US’, ‘fr-FR’). If null, returns the current locale.

return

string

The current locale

Example:

Money::locale('fr_FR');
$locale = Money::locale(); // 'fr_FR'

jsonSerializer()

Get or set the callback to use for JSON serialization.

public static function jsonSerializer(?Closure $callback = null): Closure

callback

Closure|null

default:"null"

A callback that receives a Money instance and returns an array. If null, returns the current serializer.

return

Closure

The current JSON serializer callback

Example:

Money::jsonSerializer(fn(Money $money) => [
    'amount' => (string) $money->getAmount(),
    'currency' => $money->getCurrency()->getCode(),
]);

Getter Methods

getMoney()

Get the underlying Brick\Money\Money instance.

public function getMoney(): BrickMoney

return

Brick\Money\Money

The underlying Brick Money instance

getCurrency()

Returns the Currency of this Money.

public function getCurrency(): Currency

return

Currency

The currency instance

Example:

$money = Money::of(100, 'USD');
$currency = $money->getCurrency(); // Currency instance

getContext()

Returns the Context of this Money.

public function getContext(): Context

return

Brick\Money\Context

The context instance

getAmount()

Returns the amount of this Money, as a BigDecimal.

public function getAmount(): BigDecimal

return

Brick\Math\BigDecimal

The amount as a BigDecimal

Example:

$money = Money::of('100.50', 'USD');
$amount = $money->getAmount(); // BigDecimal of 100.50

getMinorAmount()

Returns the amount of this Money in minor units (cents) for the currency.The value is returned as a BigDecimal. If this Money has a scale greater than that of the currency, the result will have a non-zero scale.For example, USD 1.23 will return a BigDecimal of 123, while USD 1.2345 will return 123.45.

public function getMinorAmount(): BigDecimal

return

Brick\Math\BigDecimal

The amount in minor units

Example:

$money = Money::of('1.23', 'USD');
$minor = $money->getMinorAmount(); // BigDecimal of 123

getUnscaledAmount()

Returns a BigInteger containing the unscaled value (all digits) of this money.For example, 123.4567 USD will return a BigInteger of 1234567.

public function getUnscaledAmount(): BigInteger

return

Brick\Math\BigInteger

The unscaled amount

getSign()

Returns the sign of this number.Returns -1 if the number is negative, 0 if zero, 1 if positive.

public function getSign(): int

return

int

-1, 0, or 1

Example:

$money = Money::of(100, 'USD');
$sign = $money->getSign(); // 1

$negative = Money::of(-50, 'USD');
$sign = $negative->getSign(); // -1

Comparison Methods

isZero()

Returns whether this money has zero value.

public function isZero(): bool

return

bool

True if the amount is zero

Example:

$money = Money::of(0, 'USD');
$money->isZero(); // true

isNegative()

Checks if this number is strictly negative.

public function isNegative(): bool

return

bool

True if the amount is negative

isNegativeOrZero()

Checks if this number is negative or zero.

public function isNegativeOrZero(): bool

return

bool

True if the amount is negative or zero

isPositive()

Checks if this number is strictly positive.

public function isPositive(): bool

return

bool

True if the amount is positive

Example:

$money = Money::of(100, 'USD');
$money->isPositive(); // true

isPositiveOrZero()

Checks if this number is positive or zero.

public function isPositiveOrZero(): bool

return

bool

True if the amount is positive or zero

compareTo()

Compares this number to the given one.Returns -1 if $this is lower than, 0 if equal to, 1 if greater than $that.

public function compareTo(Money|BigNumber|int|float|string $that): int

that

Money|BigNumber|int|float|string

required

The value to compare to

return

int

-1, 0, or 1

Example:

$money1 = Money::of(100, 'USD');
$money2 = Money::of(50, 'USD');
$money1->compareTo($money2); // 1

isEqualTo()

Checks if this number is equal to the given one.

public function isEqualTo(Money|BigNumber|int|float|string $that): bool

that

Money|BigNumber|int|float|string

required

The value to compare to

return

bool

True if equal

isLessThan()

Checks if this number is strictly lower than the given one.

public function isLessThan(Money|BigNumber|int|float|string $that): bool

that

Money|BigNumber|int|float|string

required

The value to compare to

return

bool

True if less than

isLessThanOrEqualTo()

Checks if this number is lower than or equal to the given one.

public function isLessThanOrEqualTo(Money|BigNumber|int|float|string $that): bool

that

Money|BigNumber|int|float|string

required

The value to compare to

return

bool

True if less than or equal to

isGreaterThan()

Checks if this number is strictly greater than the given one.

public function isGreaterThan(Money|BigNumber|int|float|string $that): bool

that

Money|BigNumber|int|float|string

required

The value to compare to

return

bool

True if greater than

Example:

$money1 = Money::of(100, 'USD');
$money2 = Money::of(50, 'USD');
$money1->isGreaterThan($money2); // true

isGreaterThanOrEqualTo()

Checks if this number is greater than or equal to the given one.

public function isGreaterThanOrEqualTo(Money|BigNumber|int|float|string $that): bool

that

Money|BigNumber|int|float|string

required

The value to compare to

return

bool

True if greater than or equal to

Arithmetic Operations

plus()

Returns the sum of this Money and the given amount.If the operand is a Money, it must have the same context as this Money, or an exception is thrown. This is by design, to ensure that contexts are not mixed accidentally.The resulting Money has the same context as this Money. If the result needs rounding to fit this context, a rounding mode can be provided. If a rounding mode is not provided and rounding is necessary, an exception is thrown.

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

that

Money|BigNumber|float|int|string

required

The amount to add

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode if rounding is required

return

Money

A new Money instance with the sum

Example:

$total = Money::of(1000, 'USD');
$tax = Money::of(100, 'USD');
$sum = $total->plus($tax); // $1,100.00

minus()

Returns the difference of this Money and the given amount.If the operand is a Money, it must have the same context as this Money, or an exception is thrown. This is by design, to ensure that contexts are not mixed accidentally.The resulting Money has the same context as this Money. If the result needs rounding to fit this context, a rounding mode can be provided. If a rounding mode is not provided and rounding is necessary, an exception is thrown.

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

that

Money|BigNumber|float|int|string

required

The amount to subtract

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode if rounding is required

return

Money

A new Money instance with the difference

Example:

$total = Money::of(1000, 'USD');
$tax = Money::of(100, 'USD');
$difference = $total->minus($tax); // $900.00

multipliedBy()

Returns the product of this Money and the given number.The resulting Money has the same context as this Money. If the result needs rounding to fit this context, a rounding mode can be provided. If a rounding mode is not provided and rounding is necessary, an exception is thrown.

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

that

BigNumber|float|int|string

required

The multiplier

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode if rounding is required

return

Money

A new Money instance with the product

Example:

$money = Money::of(1000, 'USD');
$doubled = $money->multipliedBy(2); // $2,000.00

dividedBy()

Returns the result of the division of this Money by the given number.The resulting Money has the same context as this Money. If the result needs rounding to fit this context, a rounding mode can be provided. If a rounding mode is not provided and rounding is necessary, an exception is thrown.

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

that

BigNumber|float|int|string

required

The divisor

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode if rounding is required

return

Money

A new Money instance with the quotient

Example:

$money = Money::of(1000, 'USD');
$half = $money->dividedBy(2); // $500.00

quotient()

Returns the quotient of the division of this Money by the given number.The given number must be an integer value. The resulting Money has the same context as this Money. This method can serve as a basis for a money allocation algorithm.

public function quotient(BigNumber|int|float|string $that): Money

that

BigNumber|int|float|string

required

The divisor (must be integer)

return

Money

The quotient

quotientAndRemainder()

Returns the quotient and the remainder of the division of this Money by the given number.The given number must be an integer value. The resulting monies have the same context as this Money. This method can serve as a basis for a money allocation algorithm.

public function quotientAndRemainder(BigNumber|int|float|string $that): array

that

BigNumber|int|float|string

required

The divisor (must be integer)

return

array{Money,Money}

An array containing [quotient, remainder]

Allocation Methods

allocate()

Allocates this Money according to a list of ratios.If the allocation yields a remainder, its amount is split over the first monies in the list, so that the total of the resulting monies is always equal to this Money.For example, given a USD 49.99 money in the default context, allocate(1, 2, 3, 4) returns [USD 5.00, USD 10.00, USD 15.00, USD 19.99]The resulting monies have the same context as this Money.

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

ratios

int...

required

Variable number of ratio integers

return

array<Money>

Array of allocated Money instances

Example:

$money = Money::of('49.99', 'USD');
$allocated = $money->allocate(1, 2, 3, 4);
// [$5.00, $10.00, $15.00, $19.99]

allocateWithRemainder()

Allocates this Money according to a list of ratios.The remainder is also present, appended at the end of the list.For example, given a USD 49.99 money in the default context, allocateWithRemainder(1, 2, 3, 4) returns [USD 4.99, USD 9.98, USD 14.97, USD 19.96, USD 0.09]The resulting monies have the same context as this Money.

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

ratios

int...

required

Variable number of ratio integers

return

array<Money>

Array of allocated Money instances with remainder

split()

Splits this Money into a number of parts.If the division of this Money by the number of parts yields a remainder, its amount is split over the first monies in the list, so that the total of the resulting monies is always equal to this Money.For example, given a USD 100.00 money in the default context, split(3) returns [USD 33.34, USD 33.33, USD 33.33]The resulting monies have the same context as this Money.

public function split(int $parts): array

parts

int

required

Number of parts to split into

return

array<Money>

Array of split Money instances

Example:

$money = Money::of(100, 'USD');
$parts = $money->split(3);
// [$33.34, $33.33, $33.33]

splitWithRemainder()

Splits this Money into a number of parts and a remainder.For example, given a USD 100.00 money in the default context, splitWithRemainder(3) returns [USD 33.33, USD 33.33, USD 33.33, USD 0.01]The resulting monies have the same context as this Money.

public function splitWithRemainder(int $parts): array

parts

int

required

Number of parts to split into

return

array<Money>

Array of split Money instances with remainder

Transformation Methods

abs()

Returns a Money whose value is the absolute value of this Money.The resulting Money has the same context as this Money.

public function abs(): Money

return

Money

A new Money instance with absolute value

Example:

$money = Money::of(-100, 'USD');
$absolute = $money->abs(); // $100.00

negated()

Returns a Money whose value is the negated value of this Money.The resulting Money has the same context as this Money.

public function negated(): Money

return

Money

A new Money instance with negated value

Example:

$money = Money::of(100, 'USD');
$negated = $money->negated(); // -$100.00

convertedTo()

Converts this Money to another currency, using an exchange rate.By default, the resulting Money has the same context as this Money. This can be overridden by providing a Context.For example, converting a default money of USD 1.23 to EUR with an exchange rate of 0.91 and RoundingMode::UP will yield EUR 1.12.

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

currency

Currency|string

required

The target currency

exchangeRate

BigNumber|float|int|string

required

The exchange rate to apply

context

Context|null

default:"null"

Optional context for the result

roundingMode

RoundingMode

default:"RoundingMode::UNNECESSARY"

Rounding mode if rounding is required

return

Money

A new Money instance in the target currency

Example:

$usd = Money::of(100, 'USD');
$eur = $usd->convertedTo('EUR', 0.91); // €91.00

Formatting Methods

format()

Formats this Money.Note that this method uses number_format, which internally represents values using floating point arithmetic, so discrepancies can appear when formatting very large monetary values.

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

allowWholeNumber

bool

default:"false"

If true, whole numbers are formatted without decimal places

return

string

The formatted money string

Example:

$money = Money::of(1000, 'USD');
echo $money->format(); // "$1,000.00"

$whole = Money::of(100, 'USD');
echo $whole->format(true); // "$100"

formatLocale()

Formats this Money with the given locale.Note that this method uses NumberFormatter, which internally represents values using floating point arithmetic, so discrepancies can appear when formatting very large monetary values.

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

locale

string|null

default:"null"

The locale to use (defaults to Money::locale())

allowWholeNumber

bool

default:"false"

If true, whole numbers are formatted without decimal places

callback

Closure|null

default:"null"

Optional callback to customize the NumberFormatter

return

string

The formatted money string

Example:

$money = Money::of(1000, 'USD');
echo $money->formatLocale('en_US'); // "$1,000.00"
echo $money->formatLocale('fr_FR'); // "1 000,00 $"

Serialization Methods

toArray()

Get the instance as an array.

public function toArray(): array

return

array

Array representation of the Money

Example:

$money = Money::of(100, 'USD');
$array = $money->toArray();
// [
//   'amount' => '10000',
//   'value' => '100.00',
//   'currency' => Currency instance
// ]

toJson()

Convert the object to its JSON representation.

public function toJson($options = 0): string

options

int

default:"0"

JSON encoding options

return

string

JSON string representation

jsonSerialize()

Specify data which should be serialized to JSON.

public function jsonSerialize(): array

return

array

Array to be JSON serialized

__toString()

Convert the object to its string representation.

public function __toString(): string

return

string

String representation (same as format())

Example:

$money = Money::of(100, 'USD');
echo $money; // "$100.00"

Macroable

The Money class uses Laravel’s Macroable trait, allowing you to add custom methods:

use Devhammed\LaravelBrickMoney\Money;

Money::macro('zero', fn(Currency|string $currency) => Money::of(0, $currency));

Money::macro('withPercentage', function (float $percentage): Money {
    return $this->multipliedBy(1 + ($percentage / 100));
});

$money = Money::zero('USD')->plus(100)->withPercentage(10); // $110.00

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

Documentation Index

​Class Definition

​Creating Money Instances

​of()

​ofMinor()

​ofMoney()

​Configuration Methods

​locale()

​jsonSerializer()

​Getter Methods

​getMoney()

​getCurrency()

​getContext()

​getAmount()

​getMinorAmount()

​getUnscaledAmount()

​getSign()

​Comparison Methods

​isZero()

​isNegative()

​isNegativeOrZero()

​isPositive()

​isPositiveOrZero()

​compareTo()

​isEqualTo()

​isLessThan()

​isLessThanOrEqualTo()

​isGreaterThan()

​isGreaterThanOrEqualTo()

​Arithmetic Operations

​plus()

​minus()

​multipliedBy()

​dividedBy()

​quotient()

​quotientAndRemainder()

​Allocation Methods

​allocate()

​allocateWithRemainder()

​split()

​splitWithRemainder()

​Transformation Methods

​abs()

​negated()

​convertedTo()

​Formatting Methods

​format()

​formatLocale()

​Serialization Methods

​toArray()

​toJson()

​jsonSerialize()

​__toString()

​Macroable

Build docs developers (and LLMs) love

Class Definition

Creating Money Instances

of()

ofMinor()

ofMoney()

Configuration Methods

locale()

jsonSerializer()

Getter Methods

getMoney()

getCurrency()

getContext()

getAmount()

getMinorAmount()

getUnscaledAmount()

getSign()

Comparison Methods

isZero()

isNegative()

isNegativeOrZero()

isPositive()

isPositiveOrZero()

compareTo()

isEqualTo()

isLessThan()

isLessThanOrEqualTo()

isGreaterThan()

isGreaterThanOrEqualTo()

Arithmetic Operations

plus()

minus()

multipliedBy()

dividedBy()

quotient()

quotientAndRemainder()

Allocation Methods

allocate()

allocateWithRemainder()

split()

splitWithRemainder()

Transformation Methods

abs()

negated()

convertedTo()

Formatting Methods

format()

formatLocale()

Serialization Methods

toArray()

toJson()

jsonSerialize()

__toString()

Macroable