Currency List Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require umpirsky/currency-list
   

   Add to composer.json if not using autoloading:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Umpirsky\\CurrencyList\\": "vendor/umpirsky/currency-list/src/"
       }
   }
   

   Run composer dump-autoload.

2. Basic Usage Fetch all currencies in JSON format:

   use Umpirsky\CurrencyList\CurrencyList;
   
   $currencies = CurrencyList::all('json');
   

3. First Practical Use Case Display currency names in a dropdown for a multi-language app:

   $currencyNames = CurrencyList::getNames('en'); // English names
   // or
   $currencyNames = CurrencyList::getNames('es'); // Spanish names
   

Implementation Patterns

Common Workflows

1. Language-Specific Data Fetch currency names in a specific language (e.g., for localization):

   $names = CurrencyList::getNames('fr'); // French names
   $symbols = CurrencyList::getSymbols('fr'); // French symbols (e.g., "€")
   

2. Filtering Currencies Get a specific currency by ISO code:

   $usd = CurrencyList::get('USD');
   // Returns: ['name' => 'US Dollar', 'symbol' => '$', ...]
   

3. Multi-Format Output Switch between formats (JSON, array, XML) dynamically:

   $currenciesJson = CurrencyList::all('json');
   $currenciesArray = CurrencyList::all('array');
   $currenciesXml = CurrencyList::all('xml');
   

4. Integration with Laravel Views Cache and reuse in Blade templates:

   // In a service provider or helper
   function getCurrencyNames($lang = 'en') {
       return Cache::remember("currency_names_{$lang}", now()->addYear(), function() use ($lang) {
           return CurrencyList::getNames($lang);
       });
   }
   

   Usage in Blade:

   <select>
       @foreach(getCurrencyNames($user->locale) as $code => $name)
           <option value="{{ $code }}">{{ $name }}</option>
       @endforeach
   </select>
   

5. API Responses Return formatted currency data in API responses:

   return response()->json([
       'currencies' => CurrencyList::all('array'),
       'supported_languages' => CurrencyList::getLanguages()
   ]);
   

Integration Tips

• Database Seeding Preload currencies into your database for performance:

  // In a seeder
  $currencies = CurrencyList::all('array');
  foreach ($currencies as $code => $data) {
      Currency::updateOrCreate(['code' => $code], $data);
  }
  

• Middleware for Locale Handling Dynamically fetch currencies based on user locale:

  // In a middleware
  $userLocale = app()->getLocale();
  $currencies = CurrencyList::getNames($userLocale);
  

• Validation Rules Use ISO codes for validation:

  use Illuminate\Validation\Rule;
  
  $rules = [
      'currency_code' => [
          'required',
          Rule::in(CurrencyList::getCodes())
      ]
  ];
  

Gotchas and Tips

Pitfalls

1. Language Code Sensitivity

   • Issue: CurrencyList::getNames('en_US') may not work as expected. The package uses language codes only (e.g., 'en', 'es'), not locale strings.
   • Fix: Use substr($locale, 0, 2) to extract the language code from a full locale (e.g., 'en_US' → 'en').

2. Caching Static Data

   • Issue: Repeated calls to CurrencyList::all() without caching can slow down requests.
   • Fix: Cache the result globally (e.g., in a service provider):

     Cache::remember('all_currencies', now()->addYears(1), function() {
         return CurrencyList::all('array');
     });
     

3. XML Parsing Quirks

   • Issue: The XML output may include namespaces or formatting that breaks simple parsing.
   • Fix: Use simplexml_load_string() or json_decode(json_encode(simplexml_load_string($xml)), true) to normalize.

4. Missing or Deprecated Codes

   • Issue: Some ISO 4217 codes (e.g., historical or rare currencies) may not be included.
   • Fix: Check CurrencyList::getCodes() for completeness or extend the package (see Extension Points below).

Debugging Tips

1. Verify Language Support List available languages to debug missing translations:

   dd(CurrencyList::getLanguages());
   

2. Inspect Raw Data Dump the raw array format to understand structure:

   dd(CurrencyList::all('array'));
   

3. Handle Missing Data Gracefully Use null coalescing or defaults:

   $name = CurrencyList::get('XYZ', 'name') ?? 'Unknown Currency';
   

Extension Points

1. Custom Data Formats Extend the package to support additional formats (e.g., CSV, YAML):

   // Add to CurrencyList.php (vendor override or custom class)
   public static function all($format = 'array') {
       if ($format === 'yaml') {
           return Spatie\ArrayToXml\ArrayToYaml::convert(self::getAll());
       }
       // ... existing logic
   }
   

2. Add Missing Currencies Fork the package or create a wrapper to merge custom data:

   class ExtendedCurrencyList {
       public static function getAll() {
           $base = CurrencyList::all('array');
           $base['XYZ'] = ['name' => 'Custom Currency', 'symbol' => '¤'];
           return $base;
       }
   }
   

3. Performance Optimization Override methods to lazy-load or paginate data for large datasets:

   public static function getNames($lang = 'en', $limit = null) {
       $all = self::all('array');
       return $limit ? array_slice($all, 0, $limit, true) : $all;
   }
   

4. Local Overrides Use Laravel’s config to override currency data:

   // config/currencies.php
   return [
       'overrides' => [
           'USD' => ['name' => 'Custom Dollar Name', 'symbol' => '$$']
       ]
   ];
   

   Merge in your wrapper:

   $config = config('currencies.overrides', []);
   $merged = array_merge(CurrencyList::all('array'), $config);