Currency Bundle Laravel Package

Getting Started

The first thing to establish is that this is a Symfony bundle, not a Laravel package. It ships a Bundle class, a DependencyInjection/Extension, and YAML configuration. There is no service provider, no facade, and no config file Laravel will read. If you are evaluating it for a Laravel app, the realistic answer is: read it for design ideas, then reimplement the ~200 lines you actually need with NumberFormatter and a rate table.

If you are in a Symfony (or Symfony-in-Laravel-via-bridge) context:

1. composer require flagbit/currency-bundle — expect resolution failures on modern PHP/Symfony; it predates the Symfony 5+ skeleton conventions and is archived, so treat the version constraint as a research exercise first.
2. Register the bundle in config/bundles.php (or legacy AppKernel).
3. Add a minimal config/packages/flagbit_currency.yaml with a base currency and a rate map.
4. Look first at three files: the README, DependencyInjection/Configuration.php (the authoritative list of config keys — the README is usually stale), and the CurrencyManager/converter service class under src/ or Model/. Those tell you the real API in under five minutes.
5. First use case: convert a stored amount into the display currency and format it with locale-aware separators — i.e. 1 234,50 € versus €1,234.50.

Implementation Patterns

• Convert at the presentation boundary, not the domain. Store every monetary amount in a single base currency (integer minor units) plus, where needed, the currency the customer was quoted in. Call the converter when rendering, so a rate update does not retroactively mutate historical orders.
• Wrap the service, don't scatter it. Inject the currency service into one MoneyFormatter/PricePresenter class of your own and let the rest of the app depend on that. When the bundle dies — and it will — you swap one class instead of grepping 40 controllers.
• Static rate map in config is the intended workflow. The bundle's model is a configured table of rates relative to a base currency, refreshed by you (cron, deploy, admin UI). There is no live ECB/provider polling out of the box; if you need that, you are writing the provider yourself and the bundle only gives you the formatting/conversion seam.
• Twig filter for templates, service for logic. The Twig extension is convenient for {{ price|currency('EUR') }}-style output, but keep business logic in PHP. Filters hide rounding decisions, which is exactly where currency bugs live.
• Multi-currency catalogues: store (amount_minor, currency_code) as a pair, resolve the display currency from session/locale/geo once per request, and pass it explicitly through your presenter rather than reading globals inside a template.

Gotchas and Tips

• Archived and unmaintained. Zero dependents and a near-zero score are consistent with what you'll find: no PHP 8.2+ or Symfony 6/7 support, no security backports, and no fixes for ICU changes. Do not put this on a payment path.
• Floats will bite you. If the converter returns float, round only at the final formatting step and use NumberFormatter::formatCurrency, never string concatenation. Better: keep integer cents in your own model and use the bundle only for the format call.
• Formatting ≠ conversion. NumberFormatter handles locale grouping, symbol placement, and minor-unit counts (JPY has 0 decimals, KWD has 3). Many homegrown "currency helpers" hardcode 2 decimals and are wrong for ~15 currencies. Whatever you build, get this from ICU.
• Config quirks: rate direction is the classic trap — verify whether the map is 1 base = X target or the inverse by converting 1 EUR→USD and sanity-checking the number. Also confirm the bundle's rounding mode; some implementations truncate.
• Debugging in Symfony: bin/console debug:container | grep -i currenc to find the real service id, and debug:config flagbit_currency to confirm your YAML was merged as expected.
• Extension points to look for (if you plan to fork): an exchange-rate provider interface and the Twig extension. Those are the two seams worth extracting; the DI plumbing is not.
• Laravel migration checklist: composer require symfony/intl gives you NumberFormatter and Currencies; a small Money value object plus a cached rate repository covers 95% of what this bundle does, with active maintenance and PHP 8 support.