Php Readability Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require j0k3r/php-readability
   

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

   'providers' => [
       // ...
       J0k3r\Readability\ReadabilityServiceProvider::class,
   ],
   

2. Basic Usage Extract readable content from a URL or HTML string:

   use J0k3r\Readability\Readability;
   
   // From URL
   $readability = new Readability();
   $article = $readability->getArticle('https://example.com/blog-post');
   
   // From HTML string
   $article = $readability->parse($htmlString);
   

3. First Use Case Fetch and clean a blog post for a news aggregator:

   $url = 'https://example.com/news';
   $article = Readability::fromUrl($url);
   $cleanTitle = $article->getTitle();
   $cleanContent = $article->getContent();
   

Implementation Patterns

Common Workflows

1. URL Processing Pipeline

   $urls = ['url1', 'url2', 'url3'];
   $articles = collect($urls)->map(fn($url) => Readability::fromUrl($url));
   

2. HTML Sanitization Use getContent() or getExcerpt() for cleaned output:

   $content = $article->getContent(); // Full article
   $excerpt = $article->getExcerpt(); // First paragraph
   

3. Metadata Extraction

   $title = $article->getTitle();
   $date = $article->getDate(); // Parsed publication date
   $images = $article->getImages(); // Array of featured images
   

4. Integration with Laravel

   • Queue Jobs for async processing:

     dispatch(new ProcessReadabilityJob($url));
     

   • Cache Results (TTL: 1 hour):

     $article = Cache::remember("readability:{$url}", now()->addHour(), fn() =>
         Readability::fromUrl($url)
     );
     

5. Custom Article Processing Extend the Article class:

   class CustomArticle extends \J0k3r\Readability\Article {
       public function getAuthor() {
           return $this->getMetaData('author') ?? 'Unknown';
       }
   }
   

Gotchas and Tips

Pitfalls

1. URL Whitelisting

   • The package may fail on non-HTML content (PDFs, images). Validate URLs first:

     if (!str_contains($url, ['html', 'php'])) {
         throw new \InvalidArgumentException('Unsupported URL type');
     }
     

2. Dynamic Content

   • JavaScript-rendered content won’t be parsed. Use tools like Puppeteer for SPAs.

3. Encoding Issues

   • Force UTF-8 encoding for non-ASCII content:

     $article->setContent(mb_convert_encoding($article->getContent(), 'UTF-8'));
     

4. Performance

   • Avoid processing large pages (>5MB). Use setMaxArticleLength():

     $readability->setMaxArticleLength(5000); // Limit to 5KB
     

Debugging

• Enable Debug Mode to log parsing steps:

  $readability->setDebug(true);
  

• Inspect Raw HTML before processing:

  $rawHtml = $readability->getRawContent();
  

Configuration Quirks

1. Custom Rules Override default heuristics in config/readability.php:

   'rules' => [
       'class' => ['custom-class', 'another-selector'],
   ],
   

2. Language Support

   • The package prioritizes English. For multilingual sites, adjust:

     $readability->setLanguage('es'); // Spanish
     

3. Image Handling

   • Disable image extraction if not needed:

     $readability->setExtractImages(false);
     

Extension Points

1. Pre/Post-Processing Hook into the pipeline:

   $readability->on('beforeParse', function($readability) {
       $readability->setContent(str_replace('ads', '', $readability->getContent()));
   });
   

2. Custom Article Class Override the default Article class in the service provider:

   $this->app->bind(\J0k3r\Readability\Article::class, CustomArticle::class);
   

3. API Wrapper Create a facade for cleaner syntax:

   // app/Facades/Readability.php
   public static function article($url) {
       return new Readability()->getArticle($url);
   }