Download the PHP package leancaptain/money without Composer

LeanCaptain Money

A small, framework-agnostic PHP money value object for representing, comparing, and calculating monetary values safely using integer minor units.

The package is intentionally lightweight and has no runtime dependencies.

Requirements

• PHP 8.4+

Installation

Install via Composer:

Quick Start

Monetary amounts should be provided as integers or decimal strings rather than floats.

Minor Units

Money is stored internally using integer minor units.

You can also construct money directly from minor units:

Currencies determine their own minor-unit precision.

Built-in Currencies

The package ships with a set of commonly used currencies:

• AED
• AUD
• BDT
• CAD
• CNY
• EUR
• GBP
• INR
• JPY
• SAR
• SGD
• USD

Applications are not required to use the built-in Currency enum.

Custom Currencies

Implement CurrencyContract to provide an application-specific currency:

Then use it normally:

Currency compatibility is determined by both the currency code and minor-unit precision.

Arithmetic

Addition

Subtraction

Multiplication

Division

Arithmetic operations return new Money instances. Existing instances are never mutated.

Rounding

The default rounding behavior is intentionally strict.

If a value cannot be represented exactly using the currency's minor-unit precision, a RoundingRequired exception is thrown.

Rounding can be requested explicitly:

Supported rounding modes:

• RoundingMode::REJECT
• RoundingMode::HALF_UP
• RoundingMode::DOWN

The same rules apply to calculations that require rounding:

Comparisons

You can also inspect the state of an amount:

Ordering or arithmetic between incompatible currencies throws a CurrencyMismatch exception.

The package does not perform currency conversion.

Other Operations

Negate an amount:

Get the absolute value:

Money Factory

MoneyFactory can be used when an application has default currency and rounding requirements.

This avoids repeating application defaults while keeping Money itself free from global configuration.

You can also construct values from minor units:

String Representation

Money implements Stringable.

The string representation is intentionally predictable and locale-independent.

Locale-aware presentation formatting should be handled separately by the consuming application.

JSON Serialization

Money implements JsonSerializable.

Produces:

The decimal amount is serialized as a string to avoid introducing floating-point representation into the monetary value.

Exceptions

The package provides dedicated exceptions for common invalid operations:

InvalidMoneyAmount

Thrown when an amount has invalid syntax.

RoundingRequired

Thrown when an otherwise valid value cannot be represented exactly and the rounding mode is REJECT.

CurrencyMismatch

Thrown when arithmetic or ordering is attempted between incompatible currencies.

Division by zero throws PHP's native DivisionByZeroError.

Design Principles

LeanCaptain Money intentionally follows a few simple rules:

• Monetary values are stored as integer minor units.
• Core monetary operations do not use floating-point arithmetic.
• Currency precision is explicit.
• Rounding is explicit when required.
• Money values are immutable.
• Different currencies cannot accidentally be combined.
• Consumer applications may provide their own currencies.
• The core package is framework-agnostic.
• The package has no runtime dependencies.

The goal is to provide a small, predictable money primitive rather than a complete financial or accounting framework.

Testing

Run the test suite with:

License

LeanCaptain Money is open-sourced software licensed under the MIT license.