Ellison Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require assertchris/ellison
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Analyze a sentence for readability and complexity:

   use Ellison\Ellison;
   
   $ellison = new Ellison();
   $result = $ellison->analyze("The quick brown fox jumps over the lazy dog.");
   print_r($result);
   

   Output will include metrics like Flesch-Kincaid readability score, sentence length, and word complexity flags.

3. Where to Look First:

   • Review the Ellison class for core methods.
   • Check the analyze() method for default thresholds and return structure.

Implementation Patterns

Workflow: Integrating into a Laravel App

1. Service Provider Binding (Recommended):

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Ellison::class, function ($app) {
           return new Ellison(config('ellison.thresholds'));
       });
   }
   

   Define thresholds in config/ellison.php:

   return [
       'max_sentence_length' => 20,
       'max_word_complexity' => 3, // Syllables
   ];
   

2. Form Request Validation: Use Ellison to validate user-generated content (e.g., blog posts, emails):

   use Ellison\Ellison;
   
   public function rules()
   {
       return [
           'content' => [
               'required',
               function ($attribute, $value, $fail) {
                   $ellison = app(Ellison::class);
                   $result = $ellison->analyze($value);
   
                   if ($result['is_complex']) {
                       $fail('Content is too complex. Aim for simpler sentences.');
                   }
               },
           ],
       ];
   }
   

3. Middleware for API Responses: Auto-analyze API responses before sending:

   // app/Http/Middleware/AnalyzeResponse.php
   public function handle($request, Closure $next)
   {
       $response = $next($request);
       if ($response->isJson()) {
           $content = $response->getContent();
           $ellison = app(Ellison::class);
           $metrics = $ellison->analyze($content);
   
           $response->setData([
               'content' => $content,
               'readability' => $metrics,
           ]);
       }
       return $response;
   }
   

4. Command-Line Tooling: Create an Artisan command to audit database records:

   // app/Console/Commands/AuditReadability.php
   public function handle()
   {
       $posts = Post::all();
       foreach ($posts as $post) {
           $metrics = app(Ellison::class)->analyze($post->content);
           if ($metrics['is_complex']) {
               $this->error("Post ID {$post->id}: Complexity detected.");
           }
       }
   }
   

Gotchas and Tips

Pitfalls

1. False Positives for Technical Writing: Ellison flags long sentences (e.g., legal/technical terms) as "complex." Override thresholds for domain-specific content:

   $ellison = new Ellison(['max_sentence_length' => 30]);
   

2. Syllable Counting Quirks:

   • Hyphenated words (e.g., "state-of-the-art") may split incorrectly.
   • Proper nouns (e.g., "McDonald’s") can miscount syllables. Workaround: Extend the countSyllables() method or pre-process text:

   $text = preg_replace('/-/', ' ', $text); // Split hyphens
   

3. Performance with Large Texts: Avoid analyzing multi-page documents in a single call. Split text into paragraphs:

   $paragraphs = explode("\n\n", $longText);
   array_map([$ellison, 'analyze'], $paragraphs);
   

Debugging

• Enable Verbose Output: Pass true to analyze() for detailed breakdowns:

  $ellison->analyze($text, true);
  

  Output includes:

  • Sentence-by-sentence scores.
  • Syllable counts per word.
  • Flagged "complex" words.

• Mocking for Tests: Use dependency injection to mock Ellison:

  $this->mock(Ellison::class)->shouldReceive('analyze')
      ->once()
      ->andReturn(['is_complex' => false]);
  

Extension Points

1. Custom Readability Metrics: Extend the Ellison class to add metrics (e.g., "passive voice detection"):

   class CustomEllison extends Ellison {
       public function analyze($text, $verbose = false) {
           $result = parent::analyze($text, $verbose);
           $result['passive_voice'] = $this->detectPassiveVoice($text);
           return $result;
       }
   }
   

2. Language Support: Override getLanguage() to support non-English text (e.g., Spanish):

   $ellison->setLanguage('es');
   // Or extend the class to add new language rules.
   

3. Database Storage: Store metrics in a readability_metrics table:

   // After analysis
   DB::table('readability_metrics')->insert([
       'content_id' => $post->id,
       'flesch_score' => $result['flesch_score'],
       'is_complex' => $result['is_complex'],
       'created_at' => now(),
   ]);
   

Config Quirks

• Default Thresholds: Hardcoded in the class (e.g., max_sentence_length = 15). Override via constructor:

  $ellison = new Ellison(['max_sentence_length' => 25]);
  

• Case Sensitivity: Analysis is case-insensitive by default. For case-sensitive checks (e.g., acronyms), pre-process text:

  $text = mb_strtolower($text, 'UTF-8');