Notowo Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hekmatinasser/notowo
   

   Add the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       Hekmatinasser\Notowo\NotowoServiceProvider::class,
   ],
   

2. Basic Usage: Convert a number to its word representation:

   use Hekmatinasser\Notowo\Notowo;
   
   $notowo = new Notowo;
   echo $notowo->convert(1234); // Output: "One Thousand Two Hundred Thirty Four"
   

3. First Use Case:

   • Currency Formatting: Display amounts in human-readable format (e.g., invoices, receipts).
   • Localization: Translate numbers to words for non-technical users (e.g., admin panels).

Implementation Patterns

Core Workflows

1. Dynamic Number Conversion:

   $amount = 5000.50;
   echo Notowo::convert($amount, 'en'); // "Five Thousand and Fifty Cents"
   

   • Supports decimals (e.g., 123.45 → "One Hundred Twenty Three and Forty Five Cents").

2. Language Support:

   Notowo::convert(1000, 'fa'); // Farsi/Persian output
   

   • Check config/notowo.php for available locales (e.g., en, fa).

3. Integration with Laravel:

   • Helper Function: Publish config and add to app/Helpers.php:

     if (!function_exists('number_to_words')) {
         function number_to_words($number, $locale = 'en') {
             return Notowo::convert($number, $locale);
         }
     }
     

   • Form Requests: Validate numeric inputs and convert to words for display:

     $request->validate(['amount' => 'required|numeric']);
     $formattedAmount = number_to_words($request->amount);
     

4. Custom Templates: Override default word templates (e.g., for currencies):

   Notowo::setTemplate('en', [
       'decimal' => 'Dollars and {0} Cents',
       // ... other keys
   ]);
   

Gotchas and Tips

Pitfalls

1. Locale Limitations:

   • Only supports en (English) and fa (Farsi) out-of-the-box. Extending requires manual template updates.
   • Fix: Fork the package or create a wrapper for unsupported locales.

2. Decimal Handling:

   • Assumes decimal places are separated by . (e.g., 123.45). Use number_format() for locale-specific decimals:

     $formatted = number_format($amount, 2, ',', ' ');
     Notowo::convert($formatted, 'en');
     

3. Large Numbers:

   • Performance degrades for numbers > 1,000,000. Cache results if used frequently:

     $cacheKey = "notowo_{$number}_{$locale}";
     return cache()->remember($cacheKey, now()->addHours(1), function() use ($number, $locale) {
         return Notowo::convert($number, $locale);
     });
     

4. Config Overrides:

   • Changes to config/notowo.php require reloading the config:

     $this->app['config']->set('notowo', $customConfig);
     

Debugging Tips

• Template Errors: Check config/notowo.php for missing keys or typos in custom templates.
• Locale Issues: Verify the locale string matches available options (e.g., 'en' vs 'en_US').
• Edge Cases: Test with:
  • Zero (0 → "Zero").
  • Negative numbers (returns false by default; handle manually).
  • Non-numeric inputs (throws exception; validate inputs first).

Extension Points

1. Add New Locales:

   • Extend the Notowo class or create a decorator:

     class ExtendedNotowo extends Notowo {
         public function convert($number, $locale = 'es') {
             if ($locale === 'es') {
                 $this->setTemplate('es', [...]);
             }
             return parent::convert($number, $locale);
         }
     }
     

2. Custom Number Formats:

   • Use setTemplate() to modify separators or word order:

     Notowo::setTemplate('en', [
         'separator' => ' ',
         'decimal' => '{0} Dollars {1} Cents',
     ]);
     

3. Testing:

   • Mock the Notowo class in PHPUnit:

     $mock = $this->createMock(Notowo::class);
     $mock->method('convert')->willReturn('Test Output');