Language List Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require umpirsky/language-list
   

   No additional configuration is needed—it’s a self-contained library.

2. First Use Case: Fetching Language Data Load the language list in a controller or service:

   use Umpirsky\LanguageList\LanguageList;
   
   $languageList = new LanguageList();
   $languages = $languageList->getAllLanguages();
   

   Outputs an array of all languages with ISO 639-1 codes and names in multiple languages.

3. Where to Look First

   • Core Class: Umpirsky\LanguageList\LanguageList (main entry point).
   • Data Formats: Supports JSON, XML, CSV, and PHP arrays (see getAllLanguages() variants).
   • Documentation: GitHub README (minimal but clear).

Implementation Patterns

Common Workflows

1. Fetching Languages in a Specific Format

   // JSON output
   $json = $languageList->getAllLanguages('json');
   
   // XML output
   $xml = $languageList->getAllLanguages('xml');
   

2. Filtering Languages by Code

   $english = $languageList->getLanguage('en');
   // Returns: ['name' => 'English', 'native' => 'English', ...]
   

3. Localization in Views

   // In a Blade template
   @php
       $languageList = new \Umpirsky\LanguageList\LanguageList();
       $spanishName = $languageList->getLanguage('es')['native'];
   @endphp
   <select>
       <option value="es">{{ $spanishName }}</option>
   </select>
   

4. Integration with Laravel Localization Combine with laravel-localization or spatie/laravel-translatable for dynamic language switching:

   $currentLang = app()->getLocale();
   $currentLangName = $languageList->getLanguage($currentLang)['native'];
   

5. Caching for Performance Cache the language list in a service provider:

   public function boot()
   {
       $this->app->singleton(LanguageList::class, function () {
           return Cache::remember('language-list', now()->addYear(), function () {
               return new LanguageList();
           });
       });
   }
   

Gotchas and Tips

Pitfalls

1. ISO 639-1 vs. ISO 639-2/3

   • The package uses ISO 639-1 (2-letter codes like en, es).
   • If your app uses ISO 639-2/3 (e.g., eng, spa), map them manually or use a helper:

     $iso6391To6392 = [
         'en' => 'eng',
         'es' => 'spa',
         // ...
     ];
     

2. Missing Codes

   • Not all languages have ISO 639-1 codes (e.g., zh covers both Chinese variants).
   • Check $languageList->getAllLanguages() for gaps.

3. Memory Usage

   • The full dataset (~500 languages) is lightweight, but avoid loading it repeatedly in loops.

Debugging

• Verify Data Integrity

  $allCodes = array_column($languageList->getAllLanguages(), 'code');
  sort($allCodes);
  // Compare with expected ISO 639-1 list (e.g., from [Wikipedia](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)).
  

• Locale-Specific Names If a language name is missing in a locale (e.g., ['native'] for fr in az):

  $frenchInAzerbaijani = $languageList->getLanguage('fr')['native'] ?? 'French (Azerbaijani name missing)';
  

Extension Points

1. Custom Data Formats Extend the library by adding a new format method:

   class ExtendedLanguageList extends LanguageList {
       public function getAllLanguagesAsYaml()
       {
           return yaml_encode($this->getAllLanguages());
       }
   }
   

2. Merge with User Data Override or extend the data array before passing it to views:

   $customLanguages = $languageList->getAllLanguages();
   $customLanguages[] = ['code' => 'xx', 'name' => 'Custom Language', 'native' => 'Custom'];
   

3. Testing Mock the LanguageList class in tests:

   $mock = Mockery::mock(LanguageList::class);
   $mock->shouldReceive('getLanguage')->andReturn(['code' => 'en', 'name' => 'Test']);
   

4. Performance Optimization

   • For large apps, preload the data in a global helper:

     if (!function_exists('get_language_name')) {
         function get_language_name($code) {
             static $list;
             if (!$list) {
                 $list = new LanguageList();
             }
             return $list->getLanguage($code)['native'] ?? $code;
         }
     }