Morphos Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require wapmorgan/morphos
   

   Add to config/app.php under providers (if not using autoloading):

   Wapmorgan\Morphos\MorphosServiceProvider::class,
   

2. First Use Case

   use Wapmorgan\Morphos\Morphos;
   
   $morphos = new Morphos();
   echo $morphos->declension('Иванов', 'Иван', 'Иванович', 'именительный', 'мужской'); // "Иванов Иван Иванович"
   

3. Key Entry Points

   • Morphos class (main facade)
   • Language-specific classes:
     • Wapmorgan\Morphos\Russian\... (e.g., Names, Geography)
     • Wapmorgan\Morphos\English\... (e.g., Nouns, Numbers)

Implementation Patterns

Core Workflows

1. Russian Name Inflection

   $morphos->declension('Петров', 'Алексей', 'Сергеевич', 'родительный'); // "Петрова Алексея Сергеевича"
   

   • Pattern: Chain case (именительный, родительный, etc.) + gender (мужской, женский, средний).
   • Use Case: User profiles, addresses, or formal correspondence.

2. English Pluralization

   $morphos->pluralize('child'); // "children"
   $morphos->pluralize('box');   // "boxes"
   

   • Pattern: Pass singular noun → get plural form.
   • Use Case: Dynamic UI labels, API responses, or localization.

3. Numerals and Money

   $morphos->cardinal(123); // "сто двадцать три"
   $morphos->money(123.45, 'рубль'); // "сто двадцать три рубля сорок пять копеек"
   

   • Pattern: Combine with declension for context-aware formatting (e.g., "123 рубля" vs. "123 рубль").
   • Use Case: Financial reports, invoices, or localized notifications.

4. Geographical Names

   $morphos->country('США', 'родительный'); // "США" (unchanged)
   $morphos->city('Москва', 'винительный'); // "Москву"
   

   • Pattern: Use predefined lists for countries/cities.
   • Use Case: Address validation, maps, or travel apps.

Integration Tips

• Laravel Localization: Combine with laravel-localization for language-aware routes:

  $locale = app()->getLocale();
  $morphos->setLanguage($locale === 'ru' ? 'ru' : 'en');
  

• Caching: Cache frequent inflections (e.g., user names) in Illuminate\Support\Facades\Cache:

  Cache::remember("morphos_{$user->last_name}_{$case}", 3600, fn() =>
      $morphos->declension($user->last_name, ...)
  );
  

• Validation: Use in Form Requests to validate name formats:

  public function rules()
  {
      return [
          'last_name' => ['required', Rule::callback(function ($attr, $value, $fail) {
              if (!preg_match('/^[А-Яа-я]+$/', $value)) {
                  $fail('Invalid Russian name format.');
              }
          })],
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity

   • Russian names must be in title case (e.g., Иванов, not иванов).
   • Fix: Normalize input:

     $name = mb_strtoupper($name, 'UTF-8');
     

2. Unsupported Cases/Genders

   • Not all combinations are supported (e.g., дательный + средний for names).
   • Fix: Check Morphos::SUPPORTED_CASES and Morphos::SUPPORTED_GENDERS before use.

3. English Irregular Plurals

   • Some nouns (e.g., mouse → mice) may not follow standard rules.
   • Fix: Extend the package or pre-map exceptions:

     $morphos->pluralize('mouse'); // Returns "mice" (built-in) but verify edge cases.
     

4. Performance

   • Heavy usage (e.g., looping through 1000 names) can be slow.
   • Fix: Batch process or cache results aggressively.

Debugging

• Invalid Inputs: Log unsupported cases/genders to identify gaps:

  try {
      $result = $morphos->declension($name, $case, $gender);
  } catch (\InvalidArgumentException $e) {
      Log::warning("Unsupported morphos combo: {$name}, {$case}, {$gender}");
  }
  

• Test Coverage: Use the package’s built-in tests (phpunit) as a reference for valid inputs.

Extension Points

1. Custom Dictionaries Extend Wapmorgan\Morphos\Russian\Names to add custom names:

   $morphos->addName('Смирнов', 'мужской', ['именительный' => 'Смирнов']);
   

2. Language Support Fork the repo to add Ukrainian/Belarusian by extending the base Morphos class.
3. Docker Integration Use the provided Docker image for non-PHP stacks (e.g., Node.js):

   docker run --rm wapmorgan/morphos:latest php -r '$morphos = new \Wapmorgan\Morphos\Morphos(); echo $morphos->declension("Иванов", "именительный");'
   

Config Quirks

• Default Language: Set globally in config/morphos.php (if using the service provider):

  'default_language' => 'ru',
  

• Fallback Behavior: The package defaults to returning the original input if inflection fails. Override with:

  $morphos->setFallbackStrategy(function ($input) {
      return "[$input]"; // Wrap unsupported inputs
  });