Letter Exchange Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require burxon/letter-exchange
   

   Add the service provider to config/app.php under providers:

   Burxon\LetterExchange\LetterExchangeServiceProvider::class,
   

2. First Use Case: Convert Cyrillic to Latin (e.g., for a username or slug):

   use Burxon\LetterExchange\Facades\LetterExchange;
   
   $cyrillicText = "Привет";
   $latinText = LetterExchange::cyrillicToLatin($cyrillicText);
   // Output: "Privet"
   

3. Reverse Conversion:

   $latinText = "Privet";
   $cyrillicText = LetterExchange::latinToCyrillic($latinText);
   // Output: "Привет"
   

4. Facade Alias: Publish the config (optional) to customize mappings:

   php artisan vendor:publish --provider="Burxon\LetterExchange\LetterExchangeServiceProvider"
   

Implementation Patterns

Common Workflows

1. User Input Sanitization: Convert Cyrillic usernames to Latin for consistency:

   $username = request()->input('username');
   $sanitized = LetterExchange::cyrillicToLatin($username);
   

2. Slug Generation: Create SEO-friendly URLs from Cyrillic content:

   $title = "Привет, мир!";
   $slug = Str::slug(LetterExchange::cyrillicToLatin($title));
   // Output: "privet-mir"
   

3. Two-Way Conversion in Forms: Dynamically switch between languages based on user locale:

   if (app()->getLocale() === 'en') {
       $displayText = LetterExchange::cyrillicToLatin($originalText);
   } else {
       $displayText = LetterExchange::latinToCyrillic($originalText);
   }
   

4. Batch Processing: Convert arrays or collections:

   $cyrillicArray = ["Привет", "Мир"];
   $latinArray = array_map([LetterExchange::class, 'cyrillicToLatin'], $cyrillicArray);
   

Integration Tips

• Middleware: Use for automatic conversion on incoming requests:

  public function handle($request, Closure $next) {
      $request->merge([
          'sanitized_name' => LetterExchange::cyrillicToLatin($request->name)
      ]);
      return $next($request);
  }
  

• Model Observers: Convert attributes before saving:

  public function saving(Model $model) {
      $model->slug = Str::slug(LetterExchange::cyrillicToLatin($model->title));
  }
  

• API Responses: Normalize responses for consistency:

  return response()->json([
      'name' => LetterExchange::cyrillicToLatin($user->name)
  ]);
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity: The package preserves case but relies on predefined mappings. Test edge cases like "ПриВет" (mixed case). Fix: Normalize case before conversion if needed:

   LetterExchange::cyrillicToLatin(strtolower($text));
   

2. Unmapped Characters: Special characters (e.g., ё, Ё) or non-Cyrillic/Latin letters may not convert. Fix: Extend the config (config/letter-exchange.php) or pre-filter text:

   preg_replace('/[^а-яА-Я]/u', '', $text);
   

3. Performance: Avoid converting the same text repeatedly in loops. Cache results if possible:

   $cacheKey = 'converted_'.$text;
   $converted = cache()->remember($cacheKey, now()->addHours(1), fn() =>
       LetterExchange::cyrillicToLatin($text)
   );
   

4. Locale Awareness: The package doesn’t auto-detect locale. Explicitly handle conversions based on app()->getLocale().

Debugging

• Verify Mappings: Dump the config to check for missing keys:

  dd(config('letter-exchange.mappings'));
  

• Test Edge Cases:

  $testCases = [
      "Привет", "мир", "Ёлки", "A", "a", "123", "!@#"
  ];
  foreach ($testCases as $text) {
      echo LetterExchange::cyrillicToLatin($text)."\n";
  }
  

Extension Points

1. Custom Mappings: Override defaults in config/letter-exchange.php:

   'mappings' => [
       'custom' => [
           'а' => 'a_custom',
           'б' => 'b_custom',
       ],
   ],
   

   Then use:

   LetterExchange::convert($text, 'custom');
   

2. Add New Conversion Modes: Extend the Converter class or create a new facade method by publishing and modifying the package source.

3. Reverse Lookup: For bidirectional checks, combine with array_flip:

   $latinToCyrillic = array_flip(config('letter-exchange.mappings.cyrillic_to_latin'));
   

Pro Tips

• Combine with Laravel Helpers: Chain with Str::of() for fluent syntax:

  Str::of($text)->cyrillicToLatin()->slug();
  

  (Requires extending the Str macro.)

• Database Storage: Store data in one script (e.g., Latin) and convert on display:

  // Store
  $user->save(['name' => LetterExchange::cyrillicToLatin($request->name)]);
  
  // Display
  $user->name_cyrillic = LetterExchange::latinToCyrillic($user->name);
  

• Validation: Use for input validation rules:

  $validator->addRules([
      'username' => [
          'required',
          Rule::function(fn($attribute, $value) =>
              preg_match('/^[a-z0-9_-]+$/i', LetterExchange::cyrillicToLatin($value))
          ),
      ],
  ]);