Stemmer Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dompat/stemmer-bundle
   

   Enable the bundle in config/bundles.php:

   Dompat\StemmerBundle\DompatStemmerBundle::class => ['all' => true],
   

2. First Use Case: Use the Twig |stem filter directly in templates:

   {{ 'running' | stem }}  {# Outputs: "run" #}
   

   Or inject the Stemmer service in a controller/service:

   use Dompat\Stemmer\Stemmer;
   
   public function __construct(private Stemmer $stemmer) {}
   
   public function index(): string
   {
       return $this->stemmer->stem('running'); // Returns "run"
   }
   

3. Check Configuration: Verify config/packages/dompat_stemmer.yaml (auto-generated) for available drivers (e.g., english, german). Modify if needed:

   dompat_stemmer:
       drivers:
           default: english
           custom_locale: german
   

Implementation Patterns

Core Workflows

1. Stemming in Controllers/Services: Inject Stemmer and use stem() for single words or stemAll() for arrays:

   $stemmer->stem('quickly'); // "quick"
   $stemmer->stemAll(['running', 'jumps']); // ["run", "jump"]
   

2. Twig Integration: Use the |stem filter in templates for dynamic stemming:

   {% for word in ['running', 'jumps'] %}
       {{ word | stem }} {# Outputs: "run", "jump" #}
   {% endfor %}
   

3. Custom Drivers: Implement DriverInterface and register via config/packages/dompat_stemmer.yaml:

   dompat_stemmer:
       drivers:
           custom_driver: App\Stemmer\CustomDriver
   

4. Locale-Specific Stemming: Pass a locale to the stem() method or configure a default in YAML:

   $stemmer->stem('Lauf', 'german'); // "lauf"
   

Integration Tips

• Batch Processing: Use stemAll() for bulk operations (e.g., search indexing):

  $words = ['running', 'jumps', 'quickly'];
  $stemmed = $stemmer->stemAll($words); // ["run", "jump", "quick"]
  

• Event Listeners: Hook into kernel.request to pre-stem query parameters or POST data:

  public function onKernelRequest(GetResponseEvent $event): void
  {
      $request = $event->getRequest();
      $request->query->set('q', $this->stemmer->stem($request->query->get('q')));
  }
  

• Form Data Sanitization: Stem form inputs before validation/saving:

  $stemmedInput = $stemmer->stem($request->request->get('search_term'));
  

Gotchas and Tips

Pitfalls

1. Driver Availability:

   • Only drivers from dompat/drivers are auto-registered. Missing a language? Install the driver package (e.g., composer require dompat/drivers-german).
   • Fix: Check var/cache/dev/app_config_*.php for registered drivers or manually add missing ones in YAML.

2. Case Sensitivity:

   • Stemming is case-insensitive by default, but input/output may vary:

     $stemmer->stem('Running'); // "run" (lowercase)
     

   • Tip: Normalize case before stemming if consistency is critical:

     $stemmer->stem(strtolower('Running'));
     

3. Performance:

   • Stemming is lightweight, but avoid overusing stemAll() in loops. Cache results if processing large datasets:

     $cache = $this->cache->get('stemmed_words_' . md5(serialize($words)));
     if (!$cache) {
         $cache = $stemmer->stemAll($words);
         $this->cache->set('stemmed_words_' . md5(serialize($words)), $cache, 3600);
     }
     

4. Twig Filter Scope:

   • The |stem filter uses the default driver unless overridden in Twig:

     {{ 'Lauf' | stem('german') }} {# Explicit locale #}
     

Debugging

• Check Registered Drivers: Dump the Stemmer service to verify loaded drivers:

  dump($stemmer->getDrivers()); // Array of available locales
  

• Override Core Drivers: To replace a default driver (e.g., english), configure it in YAML:

  dompat_stemmer:
      drivers:
          english: App\Stemmer\CustomEnglishDriver
  

Extension Points

1. Custom Stemmer Class: Extend Dompat\Stemmer\Stemmer to add pre/post-processing:

   class CustomStemmer extends Stemmer {
       public function stem(string $word): string {
           return parent::stem(str_replace(['-', "'"], '', $word));
       }
   }
   

   Register it in services.yaml:

   services:
       App\Stemmer\CustomStemmer: ~
       Dompat\Stemmer\Stemmer: '@App\Stemmer\CustomStemmer'
   

2. Event-Driven Stemming: Dispatch events before/after stemming (e.g., for analytics):

   $stemmer->stem($word, function(string $stemmed) {
       $this->eventDispatcher->dispatch(new StemmedEvent($stemmed));
   });
   

3. Non-Standard Locales: For unsupported languages, create a custom driver and register it as shown above. Example:

   class DutchDriver implements DriverInterface {
       public function stem(string $word): string {
           // Custom Dutch stemming logic
           return strtolower($word);
       }
   }