Download the PHP package ecommerce-utilities/money without Composer

Money (PHP 8.1)

A small, precise money helper class for arithmetic operations and comparisons with configurable decimal precision. Uses bcmath for deterministic decimal calculations.

• Namespace: Ecommerce
• PHP: 8.1+
• Requires: PHP extension ext-bcmath

Installation

• Ensure the bcmath PHP extension is enabled (e.g., sudo apt-get install php-bcmath and restart your web server/CLI).
• Include the class in your project (e.g., via PSR-4 autoloading) and use the Ecommerce namespace.

Quickstart

Controlling precision

• The default precision is 2 decimal places.
• You can set precision explicitly in several places:
  • When creating: Money::fromValue(123.456, 3)
  • In operations: Money::add($a, $b, 3)
• During operations, precision is determined as follows: 1) The provided $decimalPrecision parameter (if set), 2) otherwise, the precision of a Money operand (if present), 3) otherwise, 2.

Examples:

Rounding

Money::round($value, $decimalPrecision = null) rounds to the nearest value, with ties rounded away from zero (commercial rounding). It returns a new Money instance. Precision follows the same rules as other operations: explicit precision, otherwise the input Money precision, otherwise 2 decimal places.

Decimal values use bcround() when available (PHP 8.4+) and an equivalent BCMath fallback on PHP 8.1–8.3. Decimal strings are rounded and stored without conversion to float; use strings for values that require exact decimal precision. Scientific notation is also accepted. Float inputs retain PHP's float rounding behavior. Rounding an existing Money uses its already stored value; pass the original string when additional digits must be considered.

Null, string, and float inputs

All methods accept Money, int, float, numeric-string, or null (depending on the method):

Notes:

• fromMoney($value) returns the numeric value (float) regardless of the input type.
• The string representation is always formatted according to the set precision, e.g., "12.30".

Best practices

• Define a consistent precision for a domain (e.g., currency: 2, crypto assets: 8).
• For critical calculations, pass the precision explicitly to add/sub/mul/div.
• Use the comparison helpers instead of direct float comparisons.

API overview

• Creation:
  • Money::fromValue(null|Money|int|float|string $value, ?int $decimalPrecision = null): Money
  • Money::zero(): Money
• Arithmetic:
  • Money::add($a, $b, ?int $decimalPrecision = null): Money
  • Money::sub($a, $b, ?int $decimalPrecision = null): Money
  • Money::mul($a, $b, ?int $decimalPrecision = null): Money
  • Money::div($a, $b, ?int $decimalPrecision = null): Money
  • Money::round($value, ?int $decimalPrecision = null): Money
• Comparisons:
  • Money::isEqual($a, $b, ?int $decimalPrecision = null): bool
  • Money::isLeftSideGreater($a, $b, ?int $decimalPrecision = null): bool // true when a < b
  • Money::isRightSideGreater($a, $b, ?int $decimalPrecision = null): bool // true when a > b
• Access:
  • $money->getValue(): float
  • $money->getDecimalPrecision(): int
  • (string) $money for formatted output

License

Feel free to use this class in your projects. Contributions and improvements are welcome.