Text Functions Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alexivanou/text-functions-bundle
   

   Add to config/app.php under providers:

   Alexivanou\TextFunctionsBundle\TextFunctionsServiceProvider::class,
   

2. First Use Case Publish the config (if needed) and use the helper functions directly:

   use Alexivanou\TextFunctionsBundle\Facades\TextFunctions;
   
   // Pluralize text
   echo TextFunctions::pluralize('item', 1); // "1 item"
   echo TextFunctions::pluralize('item', 2); // "2 items"
   
   // Convert number to text
   echo TextFunctions::num2str(123); // "one hundred twenty-three"
   

3. Where to Look First

   • Facade: TextFunctions (for direct usage).
   • Service Provider: TextFunctionsServiceProvider (for customization).
   • Config: config/text-functions.php (if published).

Implementation Patterns

Common Workflows

1. Pluralization in Views

   // Blade template
   <p>{{ TextFunctions::pluralize('user', $count) }} found.</p>
   

2. Number-to-Text Conversion

   // For user-facing text (e.g., invoices)
   $amountText = TextFunctions::num2str($amount);
   

3. Custom Rules Override default pluralization rules in config/text-functions.php:

   'plural_rules' => [
       'rule' => [
           '^(.*)' => '$1s', // Default fallback
           '^(ox|box)$' => '$1en', // Special case
       ],
   ],
   

4. Integration with Forms

   // Validate and format numeric inputs
   $formattedValue = TextFunctions::num2str($request->input('quantity'));
   

Best Practices

• Localization: Use the pluralize() method for language-aware text (e.g., Spanish, Russian).
• Caching: Cache results of num2str() for static content (e.g., reports).
• Testing: Mock the facade in unit tests:

  $this->app->instance('text-functions', $mockTextFunctions);
  

Gotchas and Tips

Pitfalls

1. Proprietary License

   • Ensure compliance with the license terms (not open-source). Review composer.json for restrictions.

2. Limited Language Support

   • num2str() defaults to English. For multilingual apps, extend the TextFunctions class or use a dedicated library (e.g., laravel-localization).

3. Config Overrides

   • If publishing the config, merge custom rules carefully to avoid overriding defaults unintentionally:

     config(['text-functions.plural_rules' => array_merge(config('text-functions.plural_rules'), [...])]);
     

4. Edge Cases in num2str()

   • Handles numbers up to 999,999,999 (9 digits). For larger values, implement a fallback or use a library like number-to-words.

Debugging Tips

• Check Config Values

  php artisan config:clear
  

  Then verify with:

  dd(config('text-functions'));
  

• Facade Binding Issues If TextFunctions::pluralize() fails, rebind the facade in a service provider:

  $this->app->bind('text-functions', function () {
      return new \Alexivanou\TextFunctionsBundle\TextFunctions();
  });
  

Extension Points

1. Add Custom Functions Extend the TextFunctions class and bind it in the service provider:

   // app/Extensions/CustomTextFunctions.php
   class CustomTextFunctions extends \Alexivanou\TextFunctionsBundle\TextFunctions {
       public function abbreviate($text, $maxLength) {
           // Custom logic
       }
   }
   

2. Override Pluralization Logic Replace the entire pluralization engine by binding a custom implementation:

   $this->app->singleton('text-functions', function () {
       return new CustomPluralizer();
   });
   

3. Localization Hooks Use Laravel’s localization system to dynamically switch pluralization rules:

   $rules = config("text-functions.plural_rules.{$locale}");