Word To Number Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require djunehor/word-to-number
   

2. Publish config (optional):

   php artisan vendor:publish --provider="Djunehor\WordToNumber\WordToNumberServiceProvider"
   

   (Located at config/word-to-number.php)

3. First Use Case: Convert a simple English word-to-number:

   use Djunehor\WordToNumber\Facades\WordToNumber;
   
   $number = WordToNumber::convert('twenty-five');
   // Returns: 25
   

Where to Look First

• Facade: Djunehor\WordToNumber\Facades\WordToNumber (recommended for Laravel apps).
• Service Class: Djunehor\WordToNumber\WordToNumber (for direct instantiation).
• Config File: config/word-to-number.php (for locale customization).

Implementation Patterns

Core Workflow

1. Basic Conversion:

   $result = WordToNumber::convert('one hundred and twenty-three');
   // Returns: 123
   

   • Supports hyphenated numbers (twenty-one), "and" (one hundred and one), and ordinals (first).

2. Locale-Specific Handling:

   WordToNumber::setLocale('es'); // Spanish
   $numero = WordToNumber::convert('veinticinco');
   // Returns: 25
   

   (Check config/word-to-number.php for available locales: en, es, fr, de, it.)

3. Integration with Laravel Requests:

   $wordNumber = request('word_number');
   $numericValue = WordToNumber::convert($wordNumber);
   

4. Validation Rule:

   use Djunehor\WordToNumber\Rules\WordToNumber as WordToNumberRule;
   
   $request->validate([
       'amount' => ['required', new WordToNumberRule],
   ]);
   

Advanced Patterns

• Custom Locale Extension: Add a new locale by extending Djunehor\WordToNumber\Locales\Locale and registering it in the config.

• Batch Processing:

  $words = ['one', 'two', 'three'];
  $numbers = array_map(fn($word) => WordToNumber::convert($word), $words);
  // Returns: [1, 2, 3]
  

• Error Handling:

  try {
      $number = WordToNumber::convert('invalid-text');
  } catch (\InvalidArgumentException $e) {
      // Handle invalid input (e.g., log or return default)
  }
  

Gotchas and Tips

Pitfalls

1. Locale Mismatch:

   • Forgetting to set the locale before conversion (defaults to en).
   • Example: WordToNumber::convert('cinquante') in en locale will fail.

2. Hyphen Sensitivity:

   • Hyphens (-) are required for compound numbers (e.g., twenty-one vs. twentyone).
   • Workaround: Pre-process input to add hyphens where needed.

3. Ordinal Handling:

   • Ordinals (e.g., first, second) are converted to 1, 2, etc., but may not work for all locales.
   • Test edge cases like twenty-first (21) vs. twenty first (may fail).

4. Case Sensitivity:

   • Input must match the locale’s word casing (e.g., Twenty-Five may fail in en; use twenty-five).

5. Deprecated Methods:

   • Avoid WordToNumber::toNumber() (alias for convert() but less explicit).

Debugging Tips

• Enable Debug Mode:

  WordToNumber::setDebug(true); // Logs parsing steps to storage/logs/word-to-number.log
  

• Check Supported Words: Inspect the locale class (e.g., Djunehor\WordToNumber\Locales\EnLocale) for missing words.
• Fallback for Unknown Words: Use a try-catch block to handle unsupported inputs gracefully.

Extension Points

1. Add Custom Words: Override the locale class or extend Djunehor\WordToNumber\Locales\Locale:

   class CustomEnLocale extends \Djunehor\WordToNumber\Locales\EnLocale {
       protected $words = [
           'custom' => 999,
       ];
   }
   

   Register it in config/word-to-number.php under locales.

2. Modify Parsing Logic: Extend Djunehor\WordToNumber\WordToNumber and override parse() for custom rules.

3. Performance:

   • Cache converted results if processing the same words repeatedly:

     $cache = [];
     $number = $cache[$word] ?? WordToNumber::convert($word);