Concept

This section introduces the concept and basic features of the library

Immutability

Jim and Hannah both want to buy a copy of book priced at EUR 25.

use Money\Money;

$jimPrice = $hannahPrice = Money::EUR(2500);

Jim has a coupon for EUR 5.

$coupon = Money::EUR(500);
$jimPrice->subtract($coupon);

Because $jimPrice and $hannahPrice are the same object, you’d expect Hannah to now have the reduced price as well. To prevent this problem, Money objects are immutable. With the code above, both $jimPrice and $hannahPrice are still EUR 25:

$jimPrice->equals($hannahPrice); // true

The correct way of doing operations is:

$jimPrice = $jimPrice->subtract($coupon);
$jimPrice->lessThan($hannahPrice); // true
$jimPrice->equals(Money::EUR(2000)); // true

Integer Limit

Although in real life it is highly unprobable, you might have to deal with money values greater than the integer limit of your system (PHP_INT_MAX constant represents the maximum integer value).

In order to bypass this limit, we introduced Calculators. Based on your environment, Money automatically picks the best internally and globally. The following implementations are available:

  • BC Math (requires bcmath extension)
  • GMP (requires gmp extension)
  • Plain integer

Calculators are checked for availability in the order above. If no suitable Calculator is found Money silently falls back to the integer implementation.

Because of PHP’s integer limit, money values are stored as string internally and Money::getAmount also returns string.

use Money\Currency;
use Money\Money;

$hugeAmount = new Money('12345678901234567890', new Currency('USD'));

Note

Remember, because of the integer limit in PHP, you should inject a string that represents your huge amount.

JSON

If you want to serialize a money object into a JSON, you can just use the PHP method json_encode for that. Please find below example of how to achieve this.

use Money\Money;

$money = Money::USD(350);
$json = json_encode($money);
echo $json; // outputs '{"amount":"350","currency":"USD"}'