Money Laravel Package

Technical Evaluation

Architecture Fit

• Precision & Financial Accuracy: Brick\Money excels in financial use cases where floating-point errors are unacceptable (e.g., invoicing, payments, accounting). Its immutable design and exact arithmetic (via brick/math) align perfectly with Laravel’s need for reliable financial calculations.
• Contextual Flexibility: Supports custom contexts (e.g., CashContext for CHF rounding, AutoContext for dynamic precision), which is critical for multi-currency systems or compliance with regional financial rules.
• Immutability: Immutable Money objects prevent side effects, simplifying state management in Laravel services/repositories.

Integration Feasibility

• Laravel Ecosystem Fit: Works seamlessly with Laravel’s dependency injection (via Composer) and integrates with existing financial logic (e.g., Cart, Order, Payment models).
• Database Compatibility: Minor units (e.g., cents) can be stored as integers in databases, avoiding floating-point precision issues in MySQL/PostgreSQL.
• API/Validation Layer: Can replace or augment Laravel’s built-in validation (e.g., numeric|min:0 for amounts) with strict currency/currency-mismatch checks.

Technical Risk

• Breaking Changes: Pre-1.0 releases may introduce breaking changes (e.g., currency updates). Locking to 0.x.* mitigates this.
• Performance: GMP/BCMath extensions are recommended for large-scale calculations. Without them, performance may degrade for complex operations (e.g., RationalMoney).
• Currency Updates: ISO 4217 compliance requires periodic updates. Automated dependency updates (e.g., Laravel Forge/Envoyer) can handle this.

Key Questions

1. Currency Handling: How will currency conversion (e.g., USD → EUR) be managed? Will this package be extended with a CurrencyConverter or integrated with a service like laravel-money?
2. Legacy Systems: How will existing floating-point-based financial logic (e.g., legacy decimal(10,2) fields) migrate to Money objects?
3. Testing: Will unit tests cover edge cases (e.g., rounding modes, RationalMoney precision)?
4. Localization: Does the app need locale-specific formatting (e.g., €1,000.00 vs. 1,000.00 USD)? If so, how will this integrate with Laravel’s localization?

Integration Approach

Stack Fit

• PHP 8.2+: Aligns with Laravel’s current LTS support (PHP 8.2+).
• Composer: Zero-config integration via composer require brick/money.
• Laravel Services: Ideal for:
  • Order/Payment Processing: Replace float amounts with Money objects in OrderService, PaymentGateway integrations.
  • Reporting: Use MoneyBag for multi-currency financial reports.
  • Validation: Custom Laravel validators for Money objects (e.g., validateMoney(Money::of($request->amount, $request->currency))).

Migration Path

1. Phase 1: New Features
   • Introduce Money objects in new financial features (e.g., subscriptions, refunds) without touching legacy code.
   • Use dependency injection to pass Money objects to services.
2. Phase 2: Legacy Refactoring
   • Replace floating-point amounts in databases with minor units (e.g., amount_in_cents).
   • Create facade methods to convert between Money and legacy float values (e.g., Money::fromLegacyFloat($amount, $currency)).
3. Phase 3: Full Adoption
   • Deprecate legacy financial logic in favor of Money-based operations.
   • Update APIs to accept/reject Money objects (e.g., JSON API serialization/deserialization).

Compatibility

• Database: Store minor units as integers (e.g., amount_cents for USD) to avoid precision loss.
• APIs:
  • Request: Accept amounts as strings (e.g., "123.45") or JSON objects ({"amount": "123.45", "currency": "USD"}).
  • Response: Serialize Money objects to JSON with toString() or custom encoders.
• Third-Party Integrations: Use adapters to convert between Money and external APIs (e.g., Stripe, PayPal).

Sequencing

1. Proof of Concept: Test Money operations in a sandbox (e.g., order calculations, tax logic).
2. Core Integration: Integrate with Laravel’s Money facade or service container.
3. Database Migration: Backfill minor units for existing records.
4. Performance Testing: Benchmark Money operations with/without GMP/BCMath.
5. Rollout: Gradual replacement of financial logic in high-risk areas (e.g., payments) first.

Operational Impact

Maintenance

• Dependency Updates: Monitor brick/money for breaking changes (e.g., currency updates). Use Laravel’s composer.json conflict rules to enforce version locks.
• Currency Data: Ensure the IsoCurrencyProvider is kept up-to-date with ISO 4217 changes. Automate updates via CI/CD.
• Documentation: Document Money-specific behaviors (e.g., rounding modes, context usage) in API contracts and internal wikis.

Support

• Debugging: Immutable objects simplify debugging (no hidden state changes). Use Money::toString() for logging.
• Edge Cases: Prepare for:
  • Rounding Modes: Ensure all financial operations explicitly handle rounding (e.g., RoundingMode::HalfUp for taxes).
  • Currency Mismatches: Validate currency consistency in transactions (e.g., throw CurrencyMismatchException in PaymentService).
• User Education: Train developers on Money vs. legacy float usage (e.g., avoid Money::of(0.1); use Money::ofMinor(10) for USD).

Scaling

• Performance:
  • GMP/BCMath: Enable these extensions for high-throughput systems (e.g., payment processing).
  • Caching: Cache Currency objects (e.g., Currency::of('USD')) if loaded frequently.
• Concurrency: Immutable objects are thread-safe; no additional synchronization needed in Laravel’s request-per-process model.
• Database: Minor-unit storage scales well for large datasets (e.g., millions of orders).

Failure Modes

• Precision Loss: Mitigate by:
  • Never using float for financial amounts.
  • Validating Money objects in input/output layers.
• Currency Updates: Plan for:
  • Deprecated currencies (e.g., CZK → CZK with new minor unit).
  • New currencies (e.g., Digital Euro).
• Rounding Errors: Document expected behaviors (e.g., SplitMode results) and test thoroughly.

Ramp-Up

• Onboarding: Provide:
  • A Laravel-specific Money facade (e.g., Money::usd($amount)).
  • Migration guides for legacy float-based code.
• Training: Workshops on:
  • Immutable design patterns.
  • Context-specific use cases (e.g., CashContext for CHF).
• Tooling: Create:
  • Laravel Artisan commands to audit Money usage.
  • Custom Tinker helpers for debugging (e.g., Money::debug($money)).