Russian Text Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require alexivanou/russian-text-bundle
   

   Register the bundle in config/bundles.php (Symfony) or config/app.php (Laravel via alexivanou/russian-text-bundle/RussianTextBundle::class).

2. First Use Case For Laravel, use the facade directly in a controller or service:

   use RussianText\RussianText;
   
   // Pluralize a number (e.g., "1 яблоко", "2 яблока", "5 яблок")
   $text = RussianText::pluralize(3, 'яблоко', 'яблока', 'яблок');
   

3. Where to Look First

   • Facade: RussianText (main entry point).
   • Documentation: Check the GitHub README for function signatures.
   • Tests: Browse tests/ for real-world usage examples.

Implementation Patterns

Common Workflows

1. Pluralization Handle Russian noun cases dynamically:

   // For "день" (day)
   $dayText = RussianText::pluralize($days, 'день', 'дня', 'дней');
   

2. Number Spelling Convert numbers to Russian words:

   $spelled = RussianText::spellNumber(123); // "сто двадцать три"
   

3. Name Inflection Adjust names for grammatical cases (e.g., "Иван" → "Ивана"):

   $inflected = RussianText::inflectName('Иван', 'genitive');
   

4. Money Formatting Format currency with proper pluralization:

   $moneyText = RussianText::formatMoney(1234.56, 'рубль', 'рубля', 'рублей');
   

5. Transliteration Convert Cyrillic to Latin:

   $translit = RussianText::transliterate('Привет'); // "Privet"
   

Integration Tips

• Validation: Use RussianText::validatePhone() or validateEmail() for Russian-specific rules.
• Localization: Combine with Laravel’s localization system for mixed-language apps.
• API Responses: Format data before sending to Russian-speaking clients:

  return response()->json([
      'message' => RussianText::pluralize($count, 'элемент', 'элемента', 'элементов')
  ]);
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity Russian inflection functions (e.g., inflectName) are case-sensitive. Ensure input matches expected format (e.g., "Иван" not "иван").

2. Pluralization Rules Some nouns have irregular plurals (e.g., "ребенок" → "дети"). Test edge cases like:

   RussianText::pluralize(2, 'ребенок', 'ребенка', 'детей'); // Returns "дети"
   

3. Transliteration Quirks

   • transliterate() may not handle all special characters (e.g., ё → yo or e).
   • For consistency, define a custom mapping in config/russian_text.php:

     'transliteration' => [
         'custom' => ['ё' => 'yo'],
     ],
     

4. Performance Heavy operations (e.g., large-scale name inflection) may slow down requests. Cache results if reused:

   $cacheKey = "inflected_{$name}_{$case}";
   $inflected = cache()->remember($cacheKey, now()->addHours(1), fn() =>
       RussianText::inflectName($name, $case)
   );
   

Debugging

• Invalid Inputs: Functions like spellNumber() throw exceptions for non-numeric inputs. Validate first:

  if (!is_numeric($input)) {
      throw new \InvalidArgumentException('Input must be numeric');
  }
  

• Phone Validation: Use validatePhone() with strict mode:

  $isValid = RussianText::validatePhone('+7 (999) 123-45-67', true); // Strict mode
  

Extension Points

1. Custom Rules Extend pluralization rules by overriding the bundle’s Pluralizer class or adding custom entries to the config:

   'plural_rules' => [
       'custom_noun' => ['singular', 'plural', 'many'],
   ],
   

2. Service Provider Bind custom implementations in Laravel’s AppServiceProvider:

   $this->app->bind(RussianText::class, function ($app) {
       return new CustomRussianText();
   });
   

3. Testing Mock the facade for unit tests:

   $this->partialMock(RussianText::class, ['pluralize'])
        ->shouldReceive('pluralize')
        ->andReturn('тест');