Iso Currencies Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Stack Alignment: The package is architecturally lightweight and complements Laravel’s dependency injection (DI) and service container natively. Its static, immutable currency dataset (ISO 4217) ensures zero runtime overhead, making it ideal for performance-sensitive applications like payment gateways, financial APIs, or multi-currency e-commerce platforms. The historical currency flagging (e.g., BGN post-2026) aligns with Laravel’s need for data consistency and regulatory compliance in distributed systems. The package’s MIT license and Composer-driven updates further reduce integration complexity.

  Key Fit Areas:

  • Monetary Operations: Perfect for Laravel apps using moneyphp/money (e.g., invoicing, subscriptions, or financial reporting).
  • Validation Layer: Can serve as a centralized ISO 4217 validator for forms, APIs, or database constraints (e.g., rejecting invalid currency codes).
  • Historical Data Handling: The automated historical flagging (e.g., BGN → EUR transition) is critical for legacy transaction processing or regulatory compliance (e.g., Eurozone adoption).

• Integration Feasibility:

  • MoneyPHP Ecosystem: The package is optimized for moneyphp/money, enabling plug-and-play integration with Laravel. Example use cases:
    • Replace hardcoded currency arrays with CurrencyRepository::getAll() for ISO-compliant currency metadata.
    • Use CurrencyRepository::getCurrency('EUR') to fetch symbols, decimal precision, or historical status dynamically.
  • Standalone Use: While not its primary purpose, the package can be abstracted for validation (e.g., form inputs, reporting) via a facade or service layer. However, this requires decoupling from MoneyPHP-specific logic (e.g., Money objects).
  • Historical Currency Support: The automated flagging (e.g., BGN deprecation) enables:
    • Dynamic validation (e.g., reject BGN post-2026).
    • Seamless migration paths for currency changes (e.g., Eurozone adoption).
    • Audit-ready compliance for financial reporting.

• Technical Risk:

  • Tight Coupling with MoneyPHP: The package assumes compatibility with moneyphp/money, which may limit flexibility if using alternative libraries (e.g., league/money). Mitigation:
    • Use a wrapper service to normalize currency data (e.g., CurrencyService interface).
    • Abstract the repository behind Laravel’s service container for loose coupling.
  • Static Data Model: The package provides no runtime updates—currency data is static at Composer install time. Mitigation:
    • Schedule regular composer fetch-update (e.g., via CI/CD or cron) to sync with ISO changes.
    • Cache the dataset in Laravel’s cache layer (e.g., Redis) for performance.
  • BC Breaks: Major versions (e.g., 2.0.0) introduced breaking changes (e.g., removed current.json). Mitigation:
    • Test thoroughly during dependency upgrades.
    • Use Composer’s platform-check to avoid unintended version conflicts.
  • Limited Extensibility: The package is ISO 4217-only—no support for cryptocurrencies, local scrip, or non-standard symbols. Mitigation:
    • Supplement with a custom extension (e.g., CurrencyRepository decorator) for non-ISO needs.

• Key Questions:

  1. Does the app use moneyphp/money?
     • If no, assess whether the package’s MoneyPHP-specific design (e.g., Money object integration) is a blocker.
  2. Are historical currency flags critical?
     • If yes, verify the package’s historical data model meets compliance needs (e.g., BGN → EUR transition logic).
  3. What’s the update cadence for currency data?
     • Plan for automated composer fetch-update (e.g., weekly CI/CD runs) to avoid stale data.
  4. How will currency data be cached?
     • Decide between file-based caching (default) or Laravel’s cache layer (e.g., Redis) for performance.
  5. Are there non-ISO 4217 currencies in scope?
     • If yes, design a hybrid solution (e.g., extend CurrencyRepository or use a decorator pattern).

Integration Approach

Stack Fit

• Laravel Compatibility: The package integrates natively with Laravel’s service container and dependency injection. Key integration points:

  • Service Provider: Bind CurrencyRepository as a singleton in AppServiceProvider:

    $this->app->singleton(CurrencyRepository::class, function ($app) {
        return new CurrencyRepository();
    });
    

  • Facade (Optional): Create a Currency facade for cleaner syntax (e.g., Currency::getAll()).
  • Configuration: Use Laravel’s config cache to store currency settings (e.g., default currency, decimal precision rules).

• MoneyPHP Alignment:

  • Primary Use Case: Replace hardcoded currency logic with moneyphp/money + iso-currencies:

    use Money\Currency\Currency;
    use Money\Currency\CurrencyRepository;
    
    $eur = $currencyRepository->getCurrency('EUR');
    $amount = new Money(1000, $eur);
    

  • Validation: Use the repository to validate currency codes before processing:

    if (!$currencyRepository->getCurrency('XXX')) {
        throw new InvalidArgumentException('Invalid currency code.');
    }
    

• Historical Currency Handling:

  • Leverage the isHistorical() method to filter deprecated currencies (e.g., BGN post-2026):

    $historicalCurrencies = array_filter(
        $currencyRepository->getAll(),
        fn(Currency $c) => $c->isHistorical()
    );
    

  • Database Migrations: Add a currency_code column with check constraints referencing the ISO list.

Migration Path

1. Assessment Phase:

   • Audit existing currency handling (e.g., hardcoded arrays, third-party APIs, or custom databases).
   • Identify pain points (e.g., manual updates, compliance gaps, or historical data issues).

2. Pilot Integration:

   • Install the package in a non-production environment:

     composer require moneyphp/iso-currencies
     

   • Replace one currency-dependent feature (e.g., a payment form or reporting tool) with the new repository.
   • Test edge cases (e.g., historical currencies, invalid codes, or decimal precision).

3. Full Migration:

   • Phase 1: Replace hardcoded currency logic with CurrencyRepository in core services (e.g., PaymentService, InvoiceGenerator).
   • Phase 2: Update database schemas to reference ISO 4217 (e.g., currency_code foreign keys).
   • Phase 3: Implement automated updates (e.g., CI/CD script to run composer fetch-update weekly).
   • Phase 4: Deprecate legacy currency handling (e.g., old config files or APIs).

4. Validation Layer:

   • Add middleware or form requests to validate currency codes:

     use Money\Currency\CurrencyRepository;
     
     public function rules()
     {
         return [
             'currency' => ['required', function ($attribute, $value, $fail) {
                 $repo = app(CurrencyRepository::class);
                 if (!$repo->getCurrency($value)) {
                     $fail('The ' . $attribute . ' must be a valid ISO currency code.');
                 }
             }],
         ];
     }
     

Compatibility

• PHP Versions: Supports PHP 8.1+ (Laravel 9+). Mitigation for older versions:
  • Use Composer’s platform constraints to pin a compatible version.
  • Consider upgrading PHP if the app is on <8.1 (e.g., Laravel 8).
• Symfony Support: Works with Symfony 5–8 (via YAML support). Mitigation for other frameworks:
  • Use the package standalone (e.g., for validation) without Symfony dependencies.
• MoneyPHP Version: Requires moneyphp/money v3.0+. Mitigation for older versions:
  • Upgrade moneyphp/money or abstract the repository to work with older APIs.

Sequencing

1. Dependency Installation:

   composer require moneyphp/iso-currencies moneyphp/m