Currency Manage Bundle Laravel Package

Getting Started

1. Install via Composer

   composer require tourze/currency-manage-bundle
   

   Note the -bundle suffix: this is a Symfony-style bundle, not a Laravel package with a ServiceProvider. Expect Doctrine entities, Symfony DI service definitions, and a *Bundle class rather than a *ServiceProvider.

2. Where to look first

   • src/ for the CurrencyManageBundle class, entity classes (e.g. Currency, ExchangeRate), and the manager/repository services.
   • config/ (or Resources/config/) for services.yaml / XML definitions you'll need to translate into a Laravel provider.
   • vendor/tourze/currency-manage-bundle/README.md — the 1.0.1 changelog is only a compare link, so source and README are your real documentation.

3. Wire it into Laravel The bundle has no extra.laravel.providers auto-discovery. Add a small app-level CurrencyServiceProvider that:

   • registers the bundle's services (copy/adapt the bundle's services.yaml),
   • binds the bundle's manager interface to its implementation,
   • publishes/generates migrations for its Doctrine entities (see Gotchas).

4. First use case: seed + convert

   use Tourze\CurrencyManageBundle\Manager\CurrencyManager;
   
   $manager = app(CurrencyManager::class);
   $manager->importIsoCurrencies();          // if provided by the bundle
   $amount = $manager->convert(100.00, 'USD', 'CNY');
   

   The concrete method names depend on the bundle version — confirm against src/ before committing.

Implementation Patterns

• Treat the bundle as a domain library, not a full framework integration. Keep its entities isolated behind your own repository/service layer so an Eloquent refactor later is mechanical.
• Bind the manager in a scoped service provider and inject it, rather than calling app(...) inline. This makes swapping in a fake trivial in tests.
• Exchange-rate refresh belongs in a scheduled job:

  // app/Console/Kernel.php or routes/console.php
  $schedule->call(fn () => app(CurrencyManager::class)->refreshRates())->hourly();
  

  Decouple the fetch call from the conversion path so a flaky rate API never blocks checkout.
• Cache conversions with a short TTL (Cache::remember("rate:USD:CNY", 300, ...)) — rate lookups are the hot path and the bundle won't cache for you.
• Store money as integers/minor units or a DECIMAL column, not floats. The bundle's entities may use float; audit and cast at your boundary.
• Formatting: use NumberFormatter (\NumberFormatter::CURRENCY) for display and let the bundle handle only the conversion math.
• Testing: point the Doctrine connection at SQLite in-memory and run your schema migrations in setUp(); assert conversions against hand-checked pairs rather than live rates.

Gotchas and Tips

• No Laravel auto-discovery. After composer require, nothing happens until you write a service provider and register the bundle's services manually. Budget for this.
• Migrations are Doctrine mappings, not Laravel migrations. You'll need doctrine/dbal and either php artisan vendor:publish-style schema export or a hand-written migration matching the entity metadata. Verify column types (especially currency code length and rate precision).
• Eloquent vs Doctrine: you cannot use the bundle's entities as Eloquent models. Either run the bundle on Doctrine alongside Eloquent (two connections/ORM stacks) or port the schema to Eloquent and use the bundle only for its manager logic.
• ISO 4217 correctness: validate currency codes at your forms/API layer — the bundle may not reject unknown codes, and a bad code propagates into rate lookups and display.
• Rounding: conversion rounding direction (half-up vs banker's) and minor-unit counts (JPY has 0 decimals, KWD has 3) are classic off-by-a-cent bugs. Set the scale explicitly and test JPY/KWD.
• Rate staleness: always store a fetched_at alongside rates and expose it; conversions using stale rates should be flagged, not silently trusted.
• 1.0.1 is an opaque patch release (compare link only). Pin to ^1.0 but read the diff before assuming behavior is unchanged; no migration or BC notes were published.
• Extension points: the cleanest customization is to decorate/override the manager service in your provider rather than editing vendor code. If the bundle resolves services by concrete class (common in Tourze bundles), you may need to rebind the FQCN.
• Debugging: if a service fails to resolve, run php artisan about and php artisan tinker to inspect the container; Symfony-style service IDs often differ from class names, so app(SomeClass::class) may miss — check the bundle's services.yaml for the exact ID.