Swap Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is designed for PHP 8.2+ and adheres to PSR standards (PSR-16 for caching, PSR-18/PSR-17 for HTTP), making it a strong fit for Laravel (which also follows PSR standards). The florianv/laravel-swap package further simplifies integration.
• Domain Alignment: Swap addresses a clear need in Laravel applications—currency conversion, multi-currency pricing, and financial reconciliation—without requiring custom logic for rate retrieval.
• Abstraction Level: Provides a high-level API while exposing lower-level control via Exchanger if needed. This aligns well with Laravel’s modularity and dependency injection patterns.

Integration Feasibility

• Minimal Boilerplate: The package requires only a few lines of code to integrate (e.g., Builder configuration) and works seamlessly with Laravel’s service container.
• Dependency Injection: Can be registered as a Laravel service provider, enabling dependency injection and configuration via config/app.php.
• Caching Integration: Leverages PSR-16 (symfony/cache or stash are common Laravel choices), which Laravel already supports natively.

Technical Risk

• Provider Reliability: Commercial providers (e.g., fastforex) may introduce latency or cost risks if not monitored. Fallback chains mitigate this but require proactive management.
• Rate Freshness: Public providers (e.g., european_central_bank) offer limited currency pairs or update frequencies, which may not suit real-time applications.
• Historical Data: Some providers lack historical rate support, which could be critical for auditing or compliance.
• Crypto Support: Limited to a subset of providers (e.g., coin_layer), which may not meet all use cases.

Key Questions

1. Rate Accuracy Requirements: Does the application need real-time rates (commercial providers) or can it tolerate delayed updates (public providers)?
2. Cost vs. Features: Will the team adopt a paid provider (e.g., fastforex) or rely on free tiers with limitations?
3. Caching Strategy: How will cached rates be invalidated (e.g., TTL-based vs. event-driven)?
4. Fallback Logic: Should failures trigger alerts, or is silent fallback sufficient?
5. Testing: How will rate fluctuations be tested in CI/CD (e.g., mocking providers)?

Integration Approach

Stack Fit

• Laravel Ecosystem: The package integrates natively with Laravel’s:
  • Service Container: Register Swap\Builder as a singleton or bind it to an interface.
  • Configuration: Store API keys in .env and provider settings in config/swap.php.
  • Caching: Use Laravel’s cache drivers (e.g., file, redis, database) as PSR-16 caches.
  • HTTP Clients: Laravel’s Http facade or Guzzle (via php-http/guzzle7-adapter) work out of the box.
• Existing Libraries: Complements libraries like moneyphp/money for amount conversion.

Migration Path

1. Pilot Phase:
   • Replace hardcoded rates or manual API calls with Swap’s Builder in a single module (e.g., checkout).
   • Use european_central_bank (free) for initial testing.
2. Production Rollout:
   • Add fastforex (or another commercial provider) as the primary source with fallbacks.
   • Configure caching (e.g., Redis with 1-hour TTL for rates).
3. Full Adoption:
   • Replace all currency conversion logic with Swap’s API.
   • Implement monitoring for provider failures and rate anomalies.

Compatibility

• PHP 8.2+: Laravel 10+ (PHP 8.1+) may require minor adjustments if using older versions.
• PSR Compliance: No conflicts with Laravel’s PSR standards.
• Database: No direct DB dependencies, but cached rates can be stored in Laravel’s cache or a dedicated table.

Sequencing

1. Setup:
   • Install dependencies: composer require florianv/swap symfony/http-client nyholm/psr7.
   • Publish config: php artisan vendor:publish --provider="Swap\ServiceProvider" (if using laravel-swap).
2. Configuration:
   • Define providers in .env (e.g., FASTFOREX_API_KEY) and config/swap.php.
3. Testing:
   • Mock providers in unit tests (e.g., using Mockery or Swap\Test\MockProvider).
   • Test fallback chains with simulated failures.
4. Deployment:
   • Start with a single provider (e.g., european_central_bank) in staging.
   • Gradually add commercial providers and fallbacks.

Operational Impact

Maintenance

• Provider Management:
  • Monitor API key usage (e.g., fastforex free tier limits).
  • Rotate keys periodically and update configurations.
• Caching:
  • Tune TTLs based on rate volatility (e.g., 1 hour for major pairs, 5 minutes for crypto).
  • Clear cache on provider outages or rate updates.
• Dependencies:
  • Update florianv/swap and its dependencies (e.g., symfony/http-client) regularly.
  • Watch for breaking changes in underlying providers (e.g., API endpoint updates).

Support

• Troubleshooting:
  • Log provider failures and fallback attempts for debugging.
  • Use ChainException to identify which providers failed.
• User Education:
  • Document supported currency pairs and rate freshness for stakeholders.
  • Train developers on fallback logic and caching behavior.
• Vendor Lock-in:
  • Risk of dependency on a single provider (mitigated by fallback chains).
  • Consider custom providers for niche use cases (e.g., internal APIs).

Scaling

• Performance:
  • Caching reduces API calls; ensure cache layer (e.g., Redis) scales with traffic.
  • Rate-limiting: Commercial providers may throttle requests; implement retries with exponential backoff.
• Multi-Region:
  • Deploy provider-specific configurations per region if latency is critical.
  • Use CDN-cached rates for public-facing applications.
• Cost:
  • Commercial providers may incur charges at scale; monitor usage (e.g., fastforex paid plans start at $18/month).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Provide a swap.php config template with commented examples.
  • Document common provider configurations (e.g., fastforex vs. european_central_bank).
• Testing:
  • Include rate conversion tests in CI (e.g., assert 1 EUR = ~1.08 USD).
  • Test edge cases: unsupported currency pairs, historical dates, and fallback scenarios.
• Monitoring:
  • Track:
    • Provider latency (e.g., fastforex vs. european_central_bank).
    • Fallback usage (indicates primary provider issues).
    • Cache hit/miss ratios.
  • Set up alerts for ChainException occurrences.
• Documentation:
  • Add Swap-specific sections to Laravel’s internal docs (e.g., "Currency Conversion").
  • Example: How to convert an order total in a multi-currency store.