Numbers To Words Bundle Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies Run pear install Numbers_Words (or pear install channel://pear.php.net/Numbers_Words-0.18.1 if version conflicts arise). Verify installation with pear list | grep Numbers_Words.

2. Bundle Installation Add the package via Composer:

   composer require celvin/numbers-to-words-bundle
   

   For development, use:

   composer require celvin/numbers-to-words-bundle dev-master
   

3. Register the Bundle Add to app/AppKernel.php:

   new celvin\NumbersToWordsBundle\celvinNumbersToWordsBundle(),
   

4. First Usage In a controller or service:

   use celvin\NumbersToWordsBundle\Numbers_Words\Numbers\Words;
   
   $converter = new Words();
   $wordedNumber = $converter->toWords("12378", 'es'); // "doce mil trescientos setenta y ocho"
   

First Use Case

Convert a numeric value (e.g., order ID, quantity, or price) to its worded equivalent for:

• User-facing displays (e.g., "Your order ID is one thousand two hundred thirty-four").
• Audit logs (e.g., "Quantity: five hundred").
• Internationalization (e.g., Spanish es, French fr, or English en locales).

Implementation Patterns

Core Workflows

1. Basic Number Conversion

   $converter = new Words();
   $result = $converter->toWords($number, $locale); // $locale: 'en', 'fr', 'es'
   

   • Example: toWords("1000", 'en') → "one thousand".

2. Currency Conversion

   $result = $converter->toCurrency(
       $amount,   // e.g., "123,56"
       $locale,   // 'en', 'fr', 'es'
       $currency, // 'USD', 'EUR', etc.
       $decimalSeparator // ',' or '.'
   );
   

   • Example: toCurrency("123,56", 'fr', 'EUR', ',') → "cent vingt-trois euros cinquante-six centimes".

3. Service Integration Bind the converter to the container (e.g., in services.yml or via autowiring):

   # config/services.yaml
   services:
       App\Service\NumberToWordsService:
           arguments:
               $converter: '@celvin.numbers_to_words.converter'
   

   Then inject the service where needed.

4. Dynamic Locale Handling Use Symfony’s Request to fetch the user’s locale:

   $locale = $request->getLocale(); // e.g., 'es_ES'
   $shortLocale = substr($locale, 0, 2); // 'es'
   $converter->toWords($number, $shortLocale);
   

Integration Tips

• Validation: Sanitize inputs to avoid edge cases (e.g., non-numeric strings).
• Caching: Cache frequent conversions (e.g., static order IDs) to avoid redundant PEAR calls.
• Testing: Mock the Words class for unit tests:

  $this->createMock(Words::class)->method('toWords')->willReturn('mocked result');
  

Gotchas and Tips

Pitfalls

1. PEAR Dependency Issues

   • Problem: Numbers_Words may fail to install due to PEAR channel issues or PHP version incompatibilities.
   • Fix: Use the explicit version (0.18.1) or check PEAR’s archive.
   • Workaround: If PEAR is unavailable, fork the bundle and replace the PEAR dependency with a pure PHP alternative (e.g., this library).

2. Locale Mismatches

   • Problem: The bundle supports en, fr, and es but may not handle regional variants (e.g., en_US vs. en_GB).
   • Fix: Normalize locales to 2-letter codes (e.g., substr($locale, 0, 2)).

3. Decimal/Currency Formatting

   • Problem: Incorrect decimal separators (e.g., , vs. .) can break currency conversion.
   • Fix: Pass the correct separator to toCurrency() (e.g., ',' for European formats).

4. Large Number Handling

   • Problem: Very large numbers (e.g., 1000000000) may produce unexpected results.
   • Tip: Test edge cases and consider pre-processing numbers (e.g., number_format()).

Debugging

• Check PEAR Installation:

  pear list | grep Numbers_Words
  

  If missing, reinstall or debug PEAR’s environment.

• Log Outputs:

  error_log($converter->toWords("123", 'en')); // Verify raw output
  

• Symfony Debug Toolbar: Use the profiler to inspect the celvinNumbersToWordsBundle if issues arise post-integration.

Extension Points

1. Custom Locales Extend the bundle by adding new locales:

   // Override the Words class or create a decorator
   class CustomWords extends Words {
       public function toWords($number, $locale) {
           if ($locale === 'de') {
               return $this->convertToGerman($number);
           }
           return parent::toWords($number, $locale);
       }
   }
   

2. Pluralization Rules Modify the underlying PEAR module’s rules (if needed) by editing the Numbers_Words PEAR package files.

3. Event Listeners Trigger events before/after conversion (e.g., for logging or formatting):

   $eventDispatcher->dispatch(new NumberToWordsEvent($number, $locale, $result));