Currency Context Laravel Package

Getting Started

Install and publish the package, then inspect the service provider before using it in application code:

composer require liberusoftware/currency-context
php artisan vendor:publish --provider="LiberuSoftware\CurrencyContext\CurrencyContextServiceProvider"
php artisan migrate

Look first at:

• config/currency-context.php for default/base currency, cache, formatter, and rate-provider settings.
• Migrations for ISO currency metadata, money columns, and effective-dated exchange-rate tables.
• The package contracts and service-provider bindings: these define the intended extension points for rates, formatting, and currency context.
• Any ISO 4217 seeder or import command. Seed currency metadata before storing money values.

The first practical use case is storing a product or invoice amount as a precise money value rather than a float, formatting it for display, and converting it to a reporting currency using the exchange rate effective on the transaction date:

use LiberuSoftware\CurrencyContext\ValueObjects\Money;

$price = Money::ofMinor(1299, 'USD'); // $12.99
echo $price->format('en_US');

$converted = $exchangeRates->convert($price, 'EUR', $invoice->issued_at);

Confirm exact class names from the source, because the package has low adoption and may rename internals between releases.

Implementation Patterns

• Store money as minor units plus currency code. Use integer minor units in the database where possible, and let the package’s money value object or cast handle formatting and arithmetic. Avoid storing monetary values as floats.
• Use currency roles instead of hardcoding. Treat base currency, reporting currency, and settlement/display currency as context-dependent values resolved through the package rather than global constants. This is important for multi-tenant or multi-country applications.
• Resolve exchange rates by effective date. For orders, invoices, refunds, and reports, convert using the rate valid on the business date, not simply “today’s rate.” Persist the selected rate identifier, rate value, and effective date alongside converted amounts for auditability.
• Integrate via contracts. Bind custom rate providers or formatters in a service provider if the package exposes contracts for them. Keep conversion behind a service so tests can swap a fixed-rate provider.
• Format at presentation boundaries. Store raw money values and convert/format in API resources, Blade views, exports, or notification builders. Do not store formatted strings as the source of truth.
• Cache rates carefully. Cache by currency pair and effective date, and invalidate when rates are imported or corrected. A cache key that omits the date will silently use the wrong rate.

Typical workflow:

1. Import ISO currency metadata and exchange rates.
2. Assign a base currency to the tenant or application context.
3. Store order/invoice amounts as money values.
4. On display or reporting, resolve the target currency and effective date.
5. Convert through the package service, persist the rate used, and format for the target locale.

Gotchas and Tips

• Low adoption means verify behavior yourself. With zero stars and zero dependents, read the migrations, contracts, and tests before relying on the package. Pin a specific version in composer.json and add integration tests around conversion and formatting.
• Check release/tag compatibility. The listed release date is unusual; confirm the tag exists, matches composer.json, and supports your Laravel and PHP versions.
• Precision and rounding are the main risk. Decide where rounding happens: at conversion, at formatting, or at persistence. Use the package’s rounding mode consistently and test half-cent and tax-calculation cases.
• Effective-date boundaries matter. Confirm whether rate windows are inclusive at the start/end and whether lookup uses dates or timestamps. Use the application timezone consistently; a rate selected at 2025-01-01 00:00 versus 2025-01-01 23:59 can differ.
• Handle missing rates explicitly. Prefer a clear exception or a configured fallback over silently returning the original amount. Log the currency pair, date, and rate row selected.
• ISO metadata can go stale. Re-run metadata imports idempotently when currencies change minor units, symbols, or numeric codes.
• Formatting is locale-sensitive. Currency symbol placement, separators, and negative-number formatting vary by locale. Test the specific locales your application supports instead of assuming $12.99 formatting globally.
• Debug by inspecting the rate table and container bindings. If conversion returns unexpected values, check the bound rate provider, the cached rate key, the selected rate row, and whether the effective date was normalized correctly.
• Use extension points deliberately. Custom rate providers, formatters, and money casts are the safest extension points; avoid editing vendor files. Publish config and override bindings in your own service provider.