Laravel Money Laravel Package

Technical Evaluation

Architecture Fit

• Monolithic vs. Microservices: Ideal for Laravel-based monolithic applications requiring consistent currency handling (e.g., e-commerce, fintech, or multi-currency SaaS platforms). Less relevant for microservices where currency logic may be decentralized.
• Domain Alignment: Fits seamlessly into financial domains (e.g., invoicing, payments, reporting) where precise currency formatting/conversion is critical. Misaligned for non-financial use cases (e.g., blogging platforms).
• Laravel Ecosystem: Leverages Laravel’s service container, facades, and config system, reducing boilerplate. Complements packages like laravel-currency or spatie/money if modularity is needed.

Integration Feasibility

• Low Coupling: Lightweight (~10K LOC) with minimal dependencies (only akaunting/money core). No database schema changes required.
• API Contracts: Provides fluent methods (Money::USD(), new Money()) and currency objects, easing adoption in existing codebases.
• Testing: Includes PHPUnit tests and CI/CD (StyleCI, GitHub Actions), but no formal API stability guarantees (e.g., semantic versioning risks for breaking changes).

Technical Risk

• Dependency on akaunting/money: Core logic relies on the standalone akaunting/money package (v4.x). Risks include:
  • Upstream deprecations (e.g., if akaunting/money drops PHP 8.0 support).
  • Inconsistent behavior if the underlying library changes (e.g., rounding rules).
• No Type Safety: Uses PHP’s dynamic typing; type hints (e.g., Currency) are runtime-only. Could lead to runtime errors if misused (e.g., invalid currency codes).
• Limited Localization: Relies on PHP’s number_format() for formatting, which may not handle edge cases (e.g., locale-specific symbols like ₹ or ¥). Requires manual overrides for non-standard formats.
• Performance: Minimal overhead for formatting/conversion, but heavy usage (e.g., batch processing) could benefit from caching (e.g., Currency objects).

Key Questions

1. Currency Scope:
   • Is the application multi-currency by design, or is this a niche feature (e.g., only USD/EUR)?
   • Are dynamic currency switches needed (e.g., user-selected currencies)?
2. Precision Requirements:
   • Does the app handle fractional cents (e.g., JPY, KRW) or require custom rounding logic?
3. Legacy Integration:
   • How will existing currency logic (e.g., hardcoded number_format() calls) migrate to this package?
4. Exchange Rates:
   • Are real-time rates needed (this package uses static rates; consider moneyphp or an API like exchangerate-api for dynamic rates).
5. Testing Coverage:
   • Are there edge cases (e.g., zero values, negative amounts, or non-standard currencies like XBT) that need validation?

Integration Approach

Stack Fit

• PHP/Laravel: Native support for Laravel’s service provider, facades, and config system. Works with:
  • Lumen: Possible with minor adjustments (e.g., manual service binding).
  • Symfony: Compatible via akaunting/money core, but Laravel-specific features (e.g., Money facade) won’t work.
• Database: No ORM requirements, but integrates well with Eloquent for monetary fields (e.g., amount columns stored as integers with Currency metadata).
• Frontend: Outputs formatted strings (e.g., $5.00), requiring no frontend changes unless using raw values (e.g., APIs).

Migration Path

1. Pilot Phase:
   • Start with non-critical routes (e.g., admin dashboards, reports) to validate formatting/conversion.
   • Replace hardcoded number_format() calls with Money::CURRENCY().
2. Incremental Replacement:
   • Step 1: Add the package and publish config. Update config/money.php for supported currencies.
   • Step 2: Create a wrapper trait/class (e.g., HasMoney) to standardize usage across models/controllers.

     trait HasMoney {
         public function formatAmount(int $amount): string {
             return Money::USD($amount);
         }
     }
     

   • Step 3: Replace legacy currency logic in:
     • Models: Use Money objects for monetary fields (e.g., protected $price; protected $currency;).
     • Views: Replace @number_format($price) with @money($price) (via a Blade directive).
     • APIs: Return Money objects serialized as {"amount": 500, "currency": "USD"}.
3. Deprecation:
   • Use Laravel’s deprecated() helper to phase out old methods.
   • Example:

     if (method_exists($this, 'oldFormatPrice')) {
         throw new \BadMethodCallException('Use formatAmount() instead.');
     }
     

Compatibility

• PHP Version: Requires PHP 8.0+ (check composer.json). Downgrade risks if using older PHP.
• Laravel Version: Tested with Laravel 9.x/10.x. May need adjustments for older versions (e.g., facades).
• Dependencies:
  • Conflicts: None reported, but avoid mixing with moneyphp (duplicate Money classes).
  • Extensions: No intl dependency (unlike moneyphp), but relies on PHP’s number_format().

Sequencing

Operational Impact

Maintenance

• Configuration: Centralized in config/money.php, reducing scattered logic. Updates (e.g., adding TRY) require config changes only.
• Updates:
  • Minor updates (e.g., bug fixes) are low-risk. Major updates (e.g., akaunting/money v5) may require:
    • Testing all currency formats.
    • Validating exchange rate logic (if extended).
• Debugging:
  • Clear error messages for invalid currencies (e.g., Money::XYZ(100)).
  • Log Currency objects for troubleshooting (e.g., Log::debug($money->getCurrency())).

Support

• Documentation: README is clear but lacks:
  • Migration guides from number_format() or moneyphp.
  • Examples for complex use cases (e.g., tax calculations).
• Community: 783 stars but no active issues/PRs. MIT license allows forks if needed.
• Vendor Lock-in: Low risk, but tied to akaunting/money’s roadmap. Consider forking if critical features are missing.

Scaling

• Performance:
  • Formatting: O(1) per operation; no bottlenecks expected.
  • Conversion: Static rates are fast, but dynamic rates (if added) could require external API calls.
• Horizontal Scaling: Stateless operations (no shared state between requests).
• Database:
  • Store monetary values as integers (e.g., amount in cents) with currency as a string.
  • Example schema:

    Schema::create('orders', function (Blueprint $table) {
        $table->id();
        $table->unsignedBigInteger('amount');
        $table->string('currency', 3); // ISO code
        $table->foreignId('user_id');
    });
    

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time: 1–2 hours to understand Money objects and Currency usage.
  • Training: Focus on:
    • Creating Money objects (Money::USD(100) vs. new Money(100, new Currency('USD'))).
    • Formatting vs. conversion (`Money::USD(100