Summarizer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require achilleskal/summarizer-bundle
   

   Add to config/app.php under providers:

   AchillesKal\SummarizerBundle\SummarizerServiceProvider::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="AchillesKal\SummarizerBundle\SummarizerServiceProvider" --tag="config"
   

2. First Use Case Summarize a string in a controller or service:

   use AchillesKal\SummarizerBundle\Facades\Summarizer;
   
   $text = "Your long text here...";
   $summary = Summarizer::summarize($text);
   return response()->json(['summary' => $summary]);
   

3. Where to Look First

   • Facade: app\Facades\Summarizer (for quick usage).
   • Service Class: AchillesKal\SummarizerBundle\Services\SummarizerService (for customization).
   • Config: config/summarizer.php (adjust summarization logic, e.g., algorithm, max_length).

Implementation Patterns

Core Workflows

1. Basic Summarization Use the facade for simplicity:

   $summary = Summarizer::summarize($articleText, ['max_length' => 100]);
   

2. Customizing the Algorithm Override the default summarizer (e.g., switch to ratio_text or textstat):

   // In a service or config:
   $summarizer = new AchillesKal\SummarizerBundle\Services\SummarizerService('textstat');
   $summary = $summarizer->summarize($text);
   

3. Integration with Eloquent Models Add a trait to models for reusable summarization:

   use AchillesKal\SummarizerBundle\Traits\Summarizable;
   
   class Article extends Model
   {
       use Summarizable;
   }
   

   Then call:

   $article->summarizeContent(); // Assumes $article->content exists
   

4. Batch Processing Process multiple texts (e.g., from a database query):

   $articles = Article::all();
   $summaries = collect($articles)->map(fn($article) =>
       Summarizer::summarize($article->content)
   );
   

5. API Integration Wrap summarization in a Laravel API resource:

   public function toArray($request)
   {
       return [
           'summary' => Summarizer::summarize($this->content),
           'original_length' => strlen($this->content),
       ];
   }
   

Gotchas and Tips

Common Pitfalls

1. Algorithm Limitations

   • The package relies on PHP libraries like textstat or ratio_text. If these are missing, summarization fails silently.
   • Fix: Ensure dependencies are installed (composer require textstat/ratio_text if needed) or handle exceptions:

     try {
         $summary = Summarizer::summarize($text);
     } catch (\Exception $e) {
         Log::error("Summarization failed: " . $e->getMessage());
         return "Fallback summary...";
     }
     

2. Config Overrides

   • Changes to config/summarizer.php (e.g., default_algorithm) may not reflect immediately if the service is cached.
   • Fix: Clear the config cache:

     php artisan config:clear
     

3. Performance with Long Texts

   • Complex algorithms (e.g., textstat) can be slow for large inputs (>5,000 words).
   • Tip: Use max_length to truncate early or implement a fallback:

     $summary = Summarizer::summarize($text, [
         'algorithm' => 'ratio_text',
         'max_length' => 200,
     ]);
     

4. Dependency Conflicts

   • The package may conflict with other text-processing libraries (e.g., spatie/array-to-xml).
   • Tip: Use autoloading aliases or namespaces to isolate dependencies.

5. Testing Edge Cases

   • Empty strings or non-text inputs (e.g., HTML) may break summarization.
   • Tip: Add validation:

     if (empty($text) || !is_string($text)) {
         return "No summary available.";
     }
     

Extension Points

1. Custom Summarizers Implement the AchillesKal\SummarizerBundle\Contracts\SummarizerInterface to add new algorithms:

   class MySummarizer implements SummarizerInterface {
       public function summarize(string $text, array $options): string {
           // Custom logic
       }
   }
   

   Register it in config/summarizer.php:

   'algorithms' => [
       'my_summarizer' => AchillesKal\MySummarizer::class,
   ],
   

2. Middleware for API Summarization Auto-summarize request/response bodies:

   public function handle($request, Closure $next) {
       $response = $next($request);
       if ($response->getContent()) {
           $response->setContent(
               Summarizer::summarize($response->getContent())
           );
       }
       return $response;
   }
   

3. Queueing Long Summarizations Offload heavy summarization to a queue (e.g., Laravel Queues):

   SummarizeJob::dispatch($text)->onQueue('summarization');
   

   Define the job:

   class SummarizeJob implements ShouldQueue {
       public function handle() {
           $summary = Summarizer::summarize($this->text);
           // Store $summary
       }
   }
   

Debugging Tips

• Log Input/Output: Add debug logs to verify text processing:

  Log::debug("Summarization input:", ['text' => $text]);
  $summary = Summarizer::summarize($text);
  Log::debug("Summarization output:", ['summary' => $summary]);
  

• Check Algorithm Output: Test each algorithm separately to isolate issues:

  $summarizers = ['ratio_text', 'textstat'];
  foreach ($summarizers as $algorithm) {
      $summary = Summarizer::summarize($text, ['algorithm' => $algorithm]);
      Log::info("Algorithm $algorithm summary:", ['summary' => $summary]);
  }