Laravel Money Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Abstraction Layer: Wraps MoneyPHP, a battle-tested library for financial calculations, reducing reinvention risk.
  • Laravel Integration: Designed for Laravel’s ecosystem (e.g., Eloquent models, service containers), aligning with existing patterns.
  • Type Safety: Leverages PHP 8+ typed properties and methods, improving developer experience and reducing runtime errors.
  • Currency Handling: Supports multi-currency operations, exchange rates, and formatting—critical for global financial applications.
  • Immutable Design: Money objects are immutable, preventing accidental state corruption in financial transactions.

• Cons:

  • Tight Coupling to MoneyPHP: Changes in MoneyPHP (e.g., breaking API updates) may require package updates or custom forks.
  • Limited Domain-Specific Features: May lack niche financial logic (e.g., tax calculations, payment gateways) without extensions.

Integration Feasibility

• Laravel Compatibility:
  • Works seamlessly with Laravel 8+ (PHP 8.0+). Tested with Laravel’s service container, Eloquent, and validation.
  • Supports dependency injection (DI) via Laravel’s IoC container, enabling modular design.
• Database Integration:
  • Recommended to store monetary values as integers (cents) in the database (e.g., 99 for $0.99) to avoid floating-point precision issues. Requires schema adjustments if not already compliant.
  • Provides Eloquent casts (MoneyCast) for automatic conversion between database storage and Money objects.
• Third-Party Services:
  • Can integrate with payment gateways (Stripe, PayPal) or accounting systems (QuickBooks) via adapters, though the package itself doesn’t include these.

Technical Risk

• Floating-Point Precision:
  • Risk: Storing monetary values as floats/decimals in databases or calculations can lead to rounding errors (e.g., 0.1 + 0.2 ≠ 0.3).
  • Mitigation: Enforce integer storage (cents) and use the package’s built-in arithmetic methods.
• Currency Exchange:
  • Risk: Exchange rates must be manually managed or fetched from an external API (e.g., Open Exchange Rates). The package doesn’t include a built-in solution.
  • Mitigation: Integrate a currency API (e.g., spatie/currency) or implement a caching layer for rates.
• Legacy Code:
  • Risk: Existing code using raw floats or strings for money may require refactoring to adopt the Money type.
  • Mitigation: Use Laravel’s Illuminate\Support\Facades\Money facade for gradual migration.
• Performance:
  • Risk: Heavy use of immutable objects or complex currency conversions could impact performance in high-throughput systems.
  • Mitigation: Benchmark critical paths and optimize caching (e.g., exchange rates).

Key Questions

1. Database Schema:
   • Are monetary values currently stored as floats/decimals? If so, how will we migrate to integer (cents) storage?
2. Currency Requirements:
   • Do we need multi-currency support, or is a single currency sufficient? If multi-currency, how will exchange rates be managed?
3. Validation Needs:
   • Are there domain-specific validation rules (e.g., minimum order amounts, tax calculations) beyond what the package provides?
4. Testing Strategy:
   • How will we test edge cases (e.g., currency rounding, exchange rate updates, concurrent transactions)?
5. Extension Points:
   • Are there gaps in the package (e.g., lack of audit logging for money changes) that require custom extensions?
6. Team Adoption:
   • How will the team adapt to the immutable Money type and new validation patterns?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Ideal for: Applications requiring financial calculations (e.g., e-commerce, SaaS subscriptions, accounting tools).
  • Anti-Patterns: Avoid for projects where money is purely decorative (e.g., displaying prices without calculations).
• PHP Version:
  • Requires PHP 8.0+. Ensure compatibility with your existing stack (e.g., Laravel 8+).
• Dependencies:
  • MoneyPHP: Core dependency. Verify no conflicts with existing MoneyPHP usage.
  • Laravel Components: Works with Eloquent, Validation, and Facades out of the box.

Migration Path

1. Assessment Phase:
   • Audit existing money-related code (e.g., database fields, calculations, APIs).
   • Identify pain points (e.g., floating-point bugs, lack of currency support).
2. Proof of Concept (PoC):
   • Implement a small feature (e.g., a product pricing endpoint) using the package.
   • Test edge cases (e.g., currency conversion, validation).
3. Incremental Rollout:
   • Phase 1: Replace raw monetary values in models with Money types and MoneyCast.
   • Phase 2: Update business logic (e.g., order totals, payments) to use Money arithmetic.
   • Phase 3: Integrate with APIs/gateways (e.g., Stripe) using the Money type.
4. Deprecation:
   • Deprecate old money-handling code with warnings, then remove in a major release.

Compatibility

• Database:
  • Action Required: Migrate monetary fields to store values in cents as integers (e.g., 99 for $0.99).
  • Tools: Use Laravel migrations to backfill data:

    Schema::table('orders', function (Blueprint $table) {
        $table->unsignedBigInteger('amount_in_cents')->nullable()->after('amount');
    });
    

• APIs:
  • Ensure API contracts (OpenAPI/Swagger) reflect the new Money type (e.g., {"amount": 500, "currency": "USD"}).
• Third-Party Libraries:
  • Check for conflicts with other money-related packages (e.g., moneyphp/money). If both are used, ensure consistent configuration.

Sequencing

1. Configuration:
   • Publish and customize config/money.php (e.g., default currency, precision).
2. Model Integration:
   • Add MoneyCast to Eloquent models:

     use Cknow\Money\Eloquent\Casts\MoneyCast;
     
     class Order extends Model {
         protected $casts = [
             'amount' => MoneyCast::class,
         ];
     }
     

3. Business Logic:
   • Replace arithmetic operations (e.g., +/- on floats) with Money methods:

     $total = Money::USD(100)->add(Money::USD(200)); // $300.00
     

4. Validation:
   • Use the package’s validators or extend Laravel’s validation rules:

     $request->validate([
         'amount' => 'required|money:USD|min:0',
     ]);
     

5. Testing:
   • Write unit tests for money operations, especially edge cases (e.g., rounding, currency conversion).
   • Use Laravel’s Money facade in tests for consistency.

Operational Impact

Maintenance

• Pros:
  • Reduced Bugs: Immutable Money objects minimize state-related bugs (e.g., accidental modifications).
  • Centralized Logic: Financial calculations are abstracted, making updates easier.
  • Community Support: Backed by MoneyPHP and Laravel communities (1000+ stars).
• Cons:
  • Configuration Drift: Custom money.php settings may diverge across environments if not managed (e.g., via Laravel Envoy or Ansible).
  • Dependency Updates: Requires monitoring for MoneyPHP/Laravel updates that may introduce breaking changes.

Support

• Developer Onboarding:
  • Pros: Clear documentation and Laravel-friendly patterns reduce learning curve.
  • Cons: Team must understand immutable objects and integer-based money storage.
• Troubleshooting:
  • Common issues:
    • Floating-point precision errors (mitigate with integer storage).
    • Currency conversion failures (ensure exchange rates are up-to-date).
    • Serialization/deserialization bugs (e.g., JSON APIs; use ->toArray()).
  • Tools: Leverage Laravel’s debugging tools (e.g., dd(), dump()) and the package’s test suite.

Scaling

• Performance:
  • Strengths: Immutable objects and integer storage are performant for most use cases.
  • Bottlenecks:
    • Currency conversions may require external API calls (cache rates aggressively).
    • High-frequency transactions (e.g., real-time payments) should be benchmarked for contention.
• Horizontal Scaling:
  • Stateless design (no shared money objects) makes it cloud/container-friendly.
  • Database schema changes (e.g., adding currency columns) may require migrations during scaling events.

Failure Modes