Money Laravel Package

Technical Evaluation

Architecture Fit

• Domain-Driven Design (DDD) Alignment: The moneyphp/money package is a near-perfect fit for financial systems, e-commerce, billing, or any domain requiring precise monetary calculations. It enforces Martin Fowler’s Money Pattern, ensuring immutability, type safety, and currency-aware operations—critical for domains where floating-point errors or incorrect currency handling could lead to financial discrepancies.
• Laravel Ecosystem Synergy: Laravel’s built-in support for eloquent models, queues, and API responses aligns well with this package. For example:
  • Eloquent Attributes: Store Money objects as JSON in database columns (via json type or Money::jsonSerialize()).
  • API Responses: Serialize Money objects directly in JSON APIs (native support via jsonSerialize).
  • Validation: Integrate with Laravel’s validator to enforce monetary constraints (e.g., min:1000 for EUR).
• Microservices/Monolith Compatibility: The package’s immutable design and currency-aware operations make it ideal for both monolithic Laravel apps and microservices (e.g., a payments service). Its PSR-compliant nature (e.g., jsonSerialize) ensures seamless interoperability with other PHP libraries.

Integration Feasibility

• Low Friction for Laravel:
  • Composer Integration: Zero-config installation (composer require moneyphp/money).
  • Service Container: Register the package as a Laravel service provider to centralize currency configurations (e.g., ISOCurrencies, CryptoCurrencies).
  • Facade Pattern: Create a Money facade to simplify usage (e.g., Money::EUR(1000)->add($fee)).
• Database Compatibility:
  • Store Money objects as JSON (PostgreSQL, MySQL 8.0+) or decimal strings (e.g., "1000.00" in a decimal(10,2) column).
  • Use eloquent-cast to automatically convert between Money objects and database values.
• API/HTTP Layer:
  • Request Validation: Use Laravel’s FormRequest to validate monetary inputs (e.g., rule('amount')->money()).
  • Response Formatting: Format Money objects for APIs using DecimalMoneyFormatter or IntlLocalizedDecimalFormatter.

Technical Risk

Key Questions for TPM

1. Currency Scope:
   • Will the system support only ISO currencies (e.g., EUR, USD) or also crypto (e.g., BTC, ETH)? This affects dependency choices (e.g., moneyphp/crypto-currencies).
2. Precision Requirements:
   • Are subunit-level operations (e.g., cents, satoshis) critical, or can the system tolerate rounding? This impacts calculator selection (bcmath vs. gmp).
3. Legacy Integration:
   • Are there existing systems using floats for money? If so, plan a migration strategy (e.g., Teller for gradual replacement).
4. Exchange Rates:
   • Will exchange rates be static (e.g., hardcoded) or dynamic (e.g., fetched from an API)? This determines whether to use FixedExchange or Exchanger.
5. Database Schema:
   • How will Money objects be persisted? Options:
     • JSON column (flexible, but requires application-layer parsing).
     • Decimal columns (e.g., amount DECIMAL(10,2) + currency VARCHAR(3)).
     • Separate tables (normalized, but complex for joins).
6. Localization:
   • Are locale-specific formatting (e.g., €1,000.00 vs. 1,000.00€) required? This impacts the choice between DecimalMoneyFormatter and IntlLocalizedDecimalFormatter.
7. Concurrency:
   • Are there high-contention scenarios (e.g., concurrent Money::allocate())? Consider thread-safe patterns or database-level locks.

Integration Approach

Stack Fit

• Laravel Core:
  • Eloquent Models: Use accessors/mutators to convert between Money objects and database values.

    // Model: Order.php
    protected $casts = [
        'amount' => Money::class, // Automatically serialize/deserialize
    ];
    

  • Validation: Extend Laravel’s validator with custom rules for monetary values.

    use Illuminate\Validation\Rule;
    
    Rule::macro('money', function ($attribute, $value, $parameters) {
        return Money::parse($value, 'USD')->isValid();
    });
    

  • API Resources: Format Money objects in responses using DecimalMoneyFormatter.

    // App\Http\Resources\OrderResource.php
    public function toArray($request) {
        return [
            'amount' => $this->whenLoaded('amount', fn () =>
                DecimalMoneyFormatter::format($this->amount)
            ),
        ];
    }
    

• Queue/Jobs:
  • Serialize Money objects in delayed jobs (e.g., RefundJob) using json_encode().
  • Deserialize in the job handler with Money::parse().
• Caching:
  • Cache currency repositories (e.g., ISOCurrencies) if loaded frequently.
  • Cache exchange rates (if dynamic) with a TTL (e.g., Cache::remember()).

Migration Path

Compatibility