Money Laravel Package

Product Decisions This Supports

• Monetary Precision & Compliance: Eliminates floating-point errors in financial calculations (e.g., 999.99 + 0.01 ≠ 1000.00), critical for payment systems, invoicing, or tax engines.
• Currency-Agnostic Architecture: Enables global product expansion by supporting ISO currencies (EUR, USD, JPY) and crypto (BTC, ETH) out-of-the-box, reducing backend complexity for multi-currency features.
• Build vs. Buy: Avoids reinventing wheel for core financial math (e.g., allocation, rounding, exchange rates). Swap integration (via voutzinos/swap) enables real-time FX rates without third-party APIs.
• Roadmap Priorities:
  • Phase 1: Replace legacy float-based money storage in databases/APIs with this package’s immutable Money objects.
  • Phase 2: Integrate with existing services (e.g., Stripe, PayPal) via adapters to standardize currency handling.
  • Phase 3: Extend to support dynamic currency rules (e.g., tax calculations per region) using the CurrencyRepository interface.
• Use Cases:
  • E-commerce: Accurate order totals, split payments, and multi-currency checkout.
  • Fintech: Loan amortization, investment calculations, or fraud detection (e.g., detecting suspicious transactions via Money::allocate).
  • Analytics: Aggregation functions (min, max, avg) for financial dashboards.

When to Consider This Package

• Adopt If:

  • Your app handles money with sub-unit precision (e.g., cents, satoshis) and risks floating-point errors.
  • You need currency conversion (static rates or real-time via Swap) without external APIs.
  • Your team uses PHP 8.0+ and can depend on BCMath (required for calculations).
  • You’re building a scalable financial system (e.g., SaaS, marketplace) where money is a core domain.

• Look Elsewhere If:

  • You’re on PHP < 8.0 (use v3.x) or lack BCMath (fallback to GMP or plain PHP, but with reduced performance).
  • Your use case is simple (e.g., displaying prices) and doesn’t require arithmetic operations.
  • You need blockchain-specific features (e.g., ERC-20 tokens)—consider web3php/web3.php or paritytech/parity-php.
  • Your stack is non-PHP (e.g., Node.js, Python)—use decimal.js or python-decimal instead.
  • You require real-time FX rates without Swap (consider commercial APIs like ExchangeRate-API or Forex.js).

How to Pitch It (Stakeholders)

For Executives:

*"This package solves a hidden technical debt bomb in our financial systems. Right now, storing $1000 as a float in our database could silently become $999.9976 due to rounding errors—costing us money in transactions or compliance fines. moneyphp/money fixes this by using strings for precision (like banks do) and adds superpowers:

• Global payments: Support 160+ currencies and crypto in one codebase.
• No more FX headaches: Built-in currency conversion with real-time rates via Swap (free tier available).
• Future-proof: Used by enterprises like Shopify and Laravel Cashier. Cost: ~$0 (MIT license). Risk: None—we can phase it in module-by-module. ROI: Zero more ‘money bugs’ and faster expansion into new markets."*

For Engineers:

*"This is the Fowler Money Pattern implemented in PHP—what we’ve been missing for years. Key wins:

• No more float hacks: All calculations use arbitrary-precision strings (BCMath/GMP fallback).
• Immutable objects: Thread-safe for microservices; no accidental mutations.
• Batteries included:
  • Currency formatting (localized or raw).
  • Exchange rates (static or dynamic via Swap).
  • Aggregations (sum, avg) for analytics.
• Zero float surprises: Money::EUR(500)->add(Money::EUR(500)) always equals 1000 (no 999.999999999999). Migration path:

1. Start by wrapping existing float money fields with Money objects in new features.
2. Use the Teller class to help legacy apps transition.
3. Replace database DECIMAL fields with strings (e.g., amount → amount_string) for long-term safety. Tradeoffs:

• Requires BCMath (enabled by default in PHP 8+).
• Slightly heavier than float for trivial math (but negligible for real-world use)."*

For Data/Compliance Teams:

*"This package eliminates rounding errors in financial reports, which is critical for:

• Audit trails: Immutable Money objects log exact transaction values.
• Tax compliance: Precise currency conversions for multi-country operations.
• Fraud detection: Anomaly detection (e.g., allocate() reveals suspicious splits). Example: If we allocate $1000 into 3 parts with ratios [1, 1, 1], this package guarantees exact splits of $333.33, $333.33, and $333.34—no floating-point approximations."*