Iso Currencies Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Stack Alignment: The package is highly compatible with Laravel’s architecture due to its Composer-based dependency model and minimalist design. It can be seamlessly integrated via Laravel’s service container (e.g., binding CurrencyRepository as a singleton in AppServiceProvider) or leveraged by Laravel packages like laravel-money. The static data structure (ISO 4217 metadata) ensures zero runtime overhead, making it ideal for performance-sensitive applications (e.g., payment gateways, financial APIs). The historical currency flag (e.g., BGN post-2026) aligns with Laravel’s need for data consistency across microservices or monolithic apps.

• Integration Feasibility:

  • MoneyPHP Ecosystem: The package is optimized for moneyphp/money, enabling plug-and-play integration with Laravel applications using this library. For example, replacing hardcoded currency arrays with CurrencyRepository::getAll() reduces technical debt and ensures ISO compliance.
  • Standalone Use Cases: While not recommended, the package can serve as a lightweight ISO 4217 data source for validation (e.g., form inputs, reporting) without moneyphp/money. However, this requires additional abstraction (e.g., a facade or service layer) to decouple it from MoneyPHP-specific logic.
  • Historical Currency Support: The automated historical flagging (e.g., BGN → EUR transition) is a critical feature for Laravel applications handling legacy transactions or regulatory compliance. It enables:
    • Dynamic validation (e.g., rejecting invalid currencies like 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’s design assumptions (e.g., Currency entity structure) may conflict with alternative libraries (e.g., league/money). Mitigation: Use a wrapper service to normalize currency data for non-MoneyPHP use cases.
  • Static Data Model: Currency updates require Composer commands (composer fetch-update), which may not suit applications needing real-time sync. Mitigation: Schedule updates via CI/CD pipelines (e.g., weekly) or supplement with a cache layer.
  • BC Breaks: Historical changes (e.g., v2.0.0’s entities removal) risk unexpected failures if versions aren’t pinned. Mitigation: Lock versions in composer.json (e.g., ^3.8) and test upgrades in staging.
  • Limited Documentation: Lack of guidance for non-MoneyPHP use cases may require internal documentation or custom adapters. Mitigation: Create a Laravel-specific wrapper to abstract MoneyPHP dependencies.

• Key Questions:

  1. Does the application use moneyphp/money?
     • If yes, integration is straightforward; if no, assess the effort to decouple MoneyPHP-specific logic.
  2. Are historical currency flags (e.g., BGN) critical for compliance?
     • If yes, validate that the package’s flags align with business rules (e.g., legacy transaction handling).
  3. Can Composer updates (fetch-update) be automated?
     • If no, evaluate manual update processes or cache strategies.
  4. Will the application support non-ISO currencies (e.g., crypto)?
     • If yes, supplement this package with an additional data source.
  5. Are there existing currency databases or APIs in use?
     • If yes, compare maintenance overhead vs. this package’s zero-cost updates.

Integration Approach

Stack Fit

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

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

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

  • Facade Pattern: Create a facade (e.g., Currency) to simplify access:

    use Illuminate\Support\Facades\Facade;
    
    class Currency extends Facade {
        protected static function getFacadeAccessor() { return 'currency'; }
    }
    

  • Laravel Money Integration: If using laravel-money, the package automatically aligns with its currency resolution logic.
  • Validation Rules: Extend Laravel’s validation with custom rules:

    use Illuminate\Validation\Rule;
    
    Rule::macro('valid_currency', function ($attribute, $value, $parameters) {
        return CurrencyRepository::getInstance()->hasCurrency($value);
    });
    

• Symfony Compatibility: The package supports Symfony 5–8 via symfony/yaml and can be integrated into Symfony’s dependency injection system. For Laravel, this is not directly relevant unless using Symfony components (e.g., HttpKernel).

Migration Path

1. Assessment Phase:

   • Audit existing currency handling (e.g., hardcoded arrays, custom APIs, or databases).
   • Identify gaps (e.g., missing historical flags, non-ISO currencies).
   • Validate compliance requirements (e.g., BGN → EUR transition rules).

2. Pilot Integration:

   • Install the package in a non-production environment:

     composer require moneyphp/iso-currencies
     composer fetch-update
     

   • Replace one currency-dependent component (e.g., a payment gateway or invoicing module) with the new CurrencyRepository.
   • Test edge cases (e.g., deprecated currencies, legacy transactions).

3. Full Rollout:

   • Bind the repository to Laravel’s container (as above).
   • Update validation logic, database schemas, and API responses to use the new data source.
   • Deprecate old currency logic in phases (e.g., via feature flags).

4. Automation:

   • Schedule Composer updates in CI/CD (e.g., GitHub Actions):

     - name: Update currencies
       run: composer fetch-update
     

   • Monitor for BC breaks in minor/patch releases.

Compatibility

• PHP Versions: Supports PHP 8.1+ (Laravel 9+). For older Laravel versions (e.g., 8.x), use v3.4.0 (last PHP 8.0-compatible release).
• Laravel Versions: No direct conflicts; works with Laravel 9–11. For Laravel 8, pin to ^3.4.
• Dependencies: Minimal; conflicts unlikely unless using alternative currency libraries.
• Historical Data: The package’s automated historical flags (e.g., BGN) require application-level logic to handle transitions (e.g., rejecting post-2026 BGN transactions).

Sequencing

1. Phase 1: Core Integration

   • Bind CurrencyRepository to Laravel’s container.
   • Replace hardcoded currency arrays with CurrencyRepository::getAll().
   • Update validation rules to use the new data source.

2. Phase 2: Compliance & Legacy Support

   • Implement historical currency checks (e.g., reject BGN post-2026).
   • Update database migrations to store currency codes as string (not enum).
   • Backfill legacy transactions with historical flags if needed.

3. Phase 3: Full Adoption

   • Deprecate custom currency logic in favor of the package.
   • Extend to API responses, reporting, and third-party integrations.
   • Automate Composer updates in CI/CD.

4. Phase 4: Optimization

   • Cache currency data in Laravel’s cache system (if updates are infrequent).
   • Add custom currency metadata (e.g., regional symbols) via a wrapper class.

Operational Impact

Maintenance

• Pros:
  • Zero manual updates: Currency data is auto-synced with ISO standards via composer fetch-update.
  • No database maintenance: Eliminates the need to manage a custom currency table.
  • Compliance automation: Historical flags (e.g., BGN) reduce manual validation effort.
• Cons:
  • Composer dependency: Requires version pinning to avoid BC breaks.
  • Update coordination: fetch-update must be scheduled (e.g., monthly) to avoid stale data.
  • Limited customization: Cannot add non-ISO currencies or custom metadata without extending the package.

Support

• Pros:
  • Standardized data: Reduces discrepancies across services (e.g., frontend vs. backend).
  • MoneyPHP ecosystem: Leverages community support