Money Laravel Package

Getting Started

1. Install via Composer: composer require moneyphp/money.
2. Initialize a Money object using minor units (e.g., cents for USD):

   use Money\Money;
   $tenEuros = new Money(1000, new Currency('EUR')); // 10.00 EUR
   

3. Perform safe operations without worrying about float precision:

   $total = $tenEuros->add(new Money(500, new Currency('EUR'))); // 15.00 EUR
   

4. Format for display using a formatter (e.g., IntlFormatter):

   use Money\Formatter\IntlMoneyFormatter;
   $formatter = new IntlMoneyFormatter(new Locale('en_US'));
   echo $formatter->format($total); // "€15.00"
   

First use case: Replace float-based amounts in invoices or cart calculations to guarantee accuracy and prevent rounding errors.

Implementation Patterns

• Domain modeling: Encapsulate Money in value objects within your domain layer (e.g., ProductPrice, CartTotal).
• Currency consistency: Always pair Money with an explicit Currency object (never rely on implicit currency context).
• Immutable workflows: Use methods like add(), subtract(), multiply(), and divide()—they return new instances, enabling safe functional-style chains:

  $priceWithTax = $originalPrice
    ->multiply(1.2, Money::ROUND_HALF_UP)
    ->add(new Money(0, $originalPrice->getCurrency())); // tax buffer
  

• Formatting integration:
  • Integrate with IntlMoneyFormatter (via ext-intl) for localization.
  • Use MoneyFormatterInterface to build custom formatters for APIs (e.g., JSON with amount_minor_units + currency_code).
• Parsing user input: Use MoneyParser (e.g., IntlMoneyParser) to convert localized strings back to Money:

  $parsed = $parser->parse('€15,00', new Currency('EUR')); // 1500 minor units
  

• Extensibility: Implement FractionalMoneyFactory for custom minor-unit logic (e.g., jPY, which uses 1-yen units but requires rounding).

Gotchas and Tips

• Minor units assumption: Money expects amounts in minor units (e.g., 100 for $1.00 USD). Never pass major units directly.
• Rounding matters: divide() and multiply() require rounding strategies (e.g., Money::ROUND_HALF_UP). Default is Money::ROUND_HALF_UP, but mismatched rounding can cause subtle drift.
• Currency validation: Currency is strict—'usd' (lowercase) is invalid; use 'USD' (uppercase ISO 4217).
• Formatter setup pitfalls: IntlMoneyFormatter requires ext-intl and correct locale/currency configuration. Test with en_US, de_DE, and ja_JP to catch region-specific formatting issues.
• Equality checks: Use equals() (checks amount + currency), not == or ===.
• Zero money: Prefer Money::zero($currency) over new Money(0, $currency) for clarity and consistency.
• Serialization: Money is serializable, but avoid storing raw Money objects in sessions/database—store ['amount' => $m->getAmount(), 'currency' => $m->getCurrency()->getCode()] instead.
• Framework integration: In Symfony/Laravel, register formatters/formatters as services and inject them into domain services (not controllers).