Getting Started

Minimal Steps

Install the Package Add to your composer.json:

composer require moneyphp/iso-currencies

Or via CLI:

composer install

Fetch Latest Currency Data Run the update command to sync with the latest ISO 4217 standards:
```
composer fetch-update
```
This populates the vendor/moneyphp/iso-currencies/data directory with the latest currency definitions.

Integrate with Laravel’s Service Container Bind the CurrencyRepository in AppServiceProvider:

use Money\Currency\CurrencyRepository;
use Money\Currency\IsoCurrencyRepository;

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

First Use Case: Validate a Currency Inject CurrencyRepository into a service or controller:

use Money\Currency\Currency;
use Money\Currency\CurrencyRepository;

public function __construct(private CurrencyRepository $currencyRepository) {}

public function validateCurrency(string $code): bool
{
    return $this->currencyRepository->getCurrency($code) !== null;
}

Implementation Patterns

Core Workflows

Currency Validation Use the repository to validate ISO 4217 codes before processing:

$currency = $this->currencyRepository->getCurrency('USD');
if ($currency === null) {
    throw new \InvalidArgumentException("Unsupported currency: USD");
}

Dynamic Currency Selection Fetch all available currencies for dropdowns or reporting:

$currencies = $this->currencyRepository->getAllCurrencies();
// Return as JSON or pass to Blade view

Precision-Aware Formatting Leverage ISO-defined decimal places (e.g., JPY = 0, EUR = 2):

$jpy = $this->currencyRepository->getCurrency('JPY');
$amount = 1000; // No decimal places for JPY

Laravel Blade Integration Pass currencies to views for dynamic UI:

return view('pricing', ['currencies' => $this->currencyRepository->getAllCurrencies()]);

In Blade:

<select name="currency">
    @foreach($currencies as $currency)
        <option value="{{ $currency->getCode() }}">
            {{ $currency->getSymbol() }} {{ $currency->getName() }}
        </option>
    @endforeach
</select>

Advanced Patterns

Caching Currency Data Cache the repository instance to avoid repeated disk reads:

$this->app->singleton(CurrencyRepository::class, function ($app) {
    return Cache::remember('currency-repository', now()->addYear(), function () {
        return new IsoCurrencyRepository();
    });
});

Custom Currency Extensions Extend the Currency class for domain-specific metadata:

class ExtendedCurrency extends \Money\Currency\Currency
{
    public function isCrypto(): bool
    {
        return $this->getCode() === 'XBT'; // Example
    }
}

Automated Updates in CI/CD Add a GitHub Actions workflow to sync currencies on PR:

jobs:
  update-currencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer fetch-update
      - uses: actions/cache@v3
        with:
          path: vendor/moneyphp/iso-currencies/data
          key: ${{ runner.os }}-currencies

Symfony Integration For Laravel apps using Symfony components, bind the repository in config/services.php:
```
$container->register('currency_repository', [IsoCurrencyRepository::class])
    ->setPublic(true);
```

Gotchas and Tips

Pitfalls

Breaking Changes in v2.0.0+
- Removed current.json and current.php files. If your code directly references these, update to use the IsoCurrencyRepository interface.
- Fix: Replace hardcoded paths with dependency injection:
```
// Old (broken)
$currency = include __DIR__.'/../../vendor/moneyphp/iso-currencies/current.php';

// New
$currency = $this->currencyRepository->getCurrency('USD');
```
Update Delays
- ISO amendments (e.g., new currencies like "XCD") may take months to appear in the package.
- Mitigation: Monitor ISO 4217 amendments and manually trigger updates if critical.
PHP Version Lock
- Dropped support for PHP <8.1 in v3.4.0. Ensure your composer.json enforces:
```
"require": {
    "php": "^8.1"
}
```

Symbol vs. Code Confusion

Some currencies share symbols (e.g., $ for USD, CAD, AUD). Always validate with getCode():

$currency = $this->currencyRepository->getCurrency('USD');
if ($currency->getSymbol() === '$') {
    // Handle USD, but not CAD/AUD
}

Debugging Tips

Verify Data Integrity Check if currencies are loaded correctly:

$allCurrencies = $this->currencyRepository->getAllCurrencies();
dd(count($allCurrencies) === 180); // ISO 4217 typically has ~180 currencies

Handle Missing Currencies Gracefully fall back for unsupported codes:

$currency = $this->currencyRepository->getCurrency('XXX'); // 'XXX' = invalid
if ($currency === null) {
    throw new \RuntimeException("Currency XXX is not ISO 4217 compliant.");
}

Debug Update Issues If composer fetch-update fails:
- Check disk permissions in vendor/moneyphp/iso-currencies/data.
- Manually verify the ISO website for changes.

Extension Points

Custom Currency Repository Override IsoCurrencyRepository to add logic:

class CustomCurrencyRepository extends IsoCurrencyRepository
{
    public function getCurrency(string $code): ?Currency
    {
        $currency = parent::getCurrency($code);
        if ($currency && $code === 'EUR') {
            $currency->setName('Euro (Custom)');
        }
        return $currency;
    }
}

Add Non-ISO Currencies Extend the repository to include cryptocurrencies:

$this->currencyRepository->addCurrency(new Currency('XBT', 'Bitcoin', 8, '₿'));

Localization Overrides Override currency names/symbols for specific locales:

$currency = $this->currencyRepository->getCurrency('JPY');
$currency->setName(__('Japanese Yen')); // Laravel localization

Performance Optimization For high-traffic apps, preload currencies in a singleton:

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $currencies = $this->app->make(CurrencyRepository::class)->getAllCurrencies();
        Cache::put('all-currencies', $currencies, now()->addDays(30));
    }
}

Iso Currencies Laravel Package