Reference Money Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package solves a critical precision issue in financial systems by storing monetary values as scaled integers (cents) as strings, avoiding floating-point arithmetic errors. This aligns well with Laravel-based financial applications (e.g., invoicing, payments, accounting).
• Doctrine Integration: Built for Doctrine ORM, but can be adapted for Laravel’s Eloquent via custom accessors/mutators or a hybrid approach (e.g., using Doctrine alongside Eloquent via doctrine/dbal).
• Laravel Compatibility: Requires PHP 8.4+, which may necessitate minor framework updates if using older Laravel versions (e.g., 10.x+). No native Laravel service provider or Facade, so integration will require manual setup.

Integration Feasibility

• Core Functionality: The package’s primary value (precision handling) is achievable via custom Eloquent traits or database-level constraints (e.g., DECIMAL(10,2)), but this package provides a reusable, standardized solution.
• Extensibility: The MIT license allows for modification, but the package lacks Laravel-specific abstractions (e.g., no Money Facade or service container bindings). Custom wrappers would be needed for seamless Laravel integration.
• Testing: Minimal test coverage in the repo (only 1 test file), raising concerns about edge-case handling (e.g., negative values, currency conversions, or multi-currency support).

Technical Risk

• Dependency Isolation: No direct Laravel dependencies; risks include:
  • ORM Conflicts: Doctrine vs. Eloquent may require a hybrid setup (e.g., using Doctrine entities alongside Eloquent models).
  • Database Schema Changes: Existing tables storing monetary values as FLOAT/DOUBLE would need migration to strings or integers.
• Performance Overhead: String storage for large datasets may impact query performance (e.g., indexing, joins). Benchmarking required.
• Future-Proofing: Last release in 2026 suggests active maintenance, but lack of stars/contributors indicates unproven adoption. Risk of abandonment or breaking changes.

Key Questions

1. Precision Requirements: Does the team’s financial data require string storage for cents, or would DECIMAL columns suffice?
2. ORM Strategy: Will the team use Doctrine alongside Eloquent, or force a full Doctrine migration?
3. Currency Scope: Does the package support multi-currency? If not, will custom extensions be needed?
4. Legacy Data: How will existing monetary values (stored as floats) be migrated without data loss?
5. Testing: Are there plans to expand test coverage for edge cases (e.g., rounding, negative values)?
6. Alternatives: Has the team evaluated Laravel-specific packages like moneyphp/money or league/money?

Integration Approach

Stack Fit

• PHP/Laravel: Compatible with Laravel 10.x+ (PHP 8.4+). For older versions, PHP upgrades or polyfills may be required.
• Database: Requires schema changes to store monetary values as strings or integers. Supports:
  • MySQL: VARCHAR(255) or BIGINT for scaled values.
  • PostgreSQL: NUMERIC or TEXT (for string storage).
• ORM: Primarily designed for Doctrine, but can be adapted for Eloquent via:
  • Option 1: Custom Eloquent Accessors/Mutators (e.g., getAmountAttribute, setAmountAttribute).
  • Option 2: Hybrid Approach: Use Doctrine entities for financial models while keeping other models in Eloquent.
  • Option 3: Wrapper Class: Create a Laravel service class that delegates to the package’s Money class.

Migration Path

1. Assessment Phase:
   • Audit existing monetary fields (identify FLOAT/DOUBLE columns).
   • Benchmark performance of string vs. DECIMAL storage.
2. Schema Migration:
   • Add new columns (e.g., amount_cents as BIGINT or amount_string as VARCHAR).
   • Backfill data using a script (e.g., amount * 100 for existing values).
   • Deprecate old columns via Laravel migrations with soft deletes or data validation.
3. ORM Integration:
   • For Eloquent: Implement a trait or observer to handle conversion:

     use BaksDev\ReferenceMoney\Money;
     
     trait UsesReferenceMoney {
         public function getAmountAttribute($value) {
             return Money::fromString($value)->getAmount();
         }
         public function setAmountAttribute($value) {
             $this->attributes['amount'] = Money::fromFloat($value)->toString();
         }
     }
     

   • For Doctrine: Use the package’s entities directly or extend them for Laravel.
4. Application Layer:
   • Replace direct monetary calculations with the package’s Money class (e.g., Money::fromFloat(123.45)->add(Money::fromFloat(50.25))).
   • Update APIs/controllers to return scaled values where needed.

Compatibility

• Laravel Ecosystem:
  • Pros: No framework-specific dependencies; works with any Laravel package using Doctrine or raw DB queries.
  • Cons: No built-in support for Laravel’s service container, caching, or queue jobs for monetary operations.
• Third-Party Packages:
  • May conflict with packages expecting native Money objects (e.g., league/money). Requires adapter layers.
• Testing Tools:
  • Works with Pest/PHPUnit, but test doubles for Money objects need to be implemented manually.

Sequencing

1. Phase 1: Proof of Concept
   • Test the package in a non-production environment with a subset of financial models.
   • Validate precision improvements and performance impact.
2. Phase 2: Schema Migration
   • Roll out database changes incrementally (e.g., per module).
   • Use feature flags to toggle old/new monetary logic.
3. Phase 3: ORM Integration
   • Implement the chosen approach (Eloquent trait, Doctrine hybrid, or wrapper).
   • Update all monetary calculations to use the package.
4. Phase 4: Deprecation
   • Phase out old monetary columns in favor of the new system.
   • Add data validation to prevent regressions.

Operational Impact

Maintenance

• Proactive:
  • Monitoring: Add database-level checks for malformed monetary strings (e.g., non-numeric values).
  • Logging: Log conversions to detect precision issues early (e.g., Money::fromString() failures).
  • Documentation: Update internal docs to reflect the new monetary handling process.
• Reactive:
  • Rollback Plan: Maintain a script to revert to DECIMAL storage if performance issues arise.
  • Dependency Updates: Watch for breaking changes in the package (though risk is low given MIT license).

Support

• Developer Onboarding:
  • Requires training on the new monetary handling pattern (e.g., always use Money objects for calculations).
  • Document common pitfalls (e.g., forgetting to scale values before storage).
• Customer Impact:
  • Minimal if the change is transparent (e.g., APIs return formatted currency strings).
  • High if internal precision issues were previously masked (e.g., rounding discrepancies in reports).

Scaling

• Database:
  • String storage may increase index sizes and slow down joins. Test with production-like datasets.
  • Consider partitioning large financial tables by date/currency.
• Application:
  • Caching: Cache frequently accessed monetary values (e.g., Money objects in Redis).
  • Batch Processing: Use Laravel queues for large-scale monetary operations (e.g., bulk payments).
• Multi-Region:
  • Ensure database collations support numeric string comparisons (e.g., utf8mb4_bin for MySQL).

Failure Modes

Ramp-Up

• Team Skills:
  • PHP: Familiarity with traits, accessors, and Doctrine (if hybrid approach is chosen).
  • Database: Experience with schema migrations and performance tuning.
• Timeline Estimate:
  • Pilot: 2–4 weeks (POC + schema changes).
  • Full Rollout: 6–8 weeks (ORM integration + app-layer updates