Laravel Link Preview Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require teners/laravel-link-preview
   

   Publish the config file:

   php artisan vendor:publish --provider="Teners\LinkPreview\LinkPreviewServiceProvider" --tag="config"
   

2. Basic Usage: Fetch a preview for a URL in a controller or service:

   use Teners\LinkPreview\Facades\LinkPreview;
   
   $preview = LinkPreview::get('https://example.com');
   

   Output will include structured data like:

   {
     "url": "https://example.com",
     "title": "Example Domain",
     "description": "This domain is for use in illustrative examples...",
     "image": "https://example.com/image.jpg",
     "favicon": "https://example.com/favicon.ico",
     "site_name": "Example Inc.",
     "type": "website"
   }
   

3. First Use Case: Display rich previews in a comment system:

   @foreach($comments as $comment)
       <div class="comment">
           <a href="{{ $comment->url }}" target="_blank">
               <img src="{{ $comment->preview->image ?? asset('fallback.png') }}" width="100">
               <h4>{{ $comment->preview->title ?? $comment->url }}</h4>
               <p>{{ Str::limit($comment->preview->description, 100) }}</p>
           </a>
       </div>
   @endforeach
   

Implementation Patterns

Core Workflows

1. Service Layer Integration: Create a dedicated service class to encapsulate preview logic:

   namespace App\Services;
   
   use Teners\LinkPreview\Facades\LinkPreview;
   
   class LinkPreviewService
   {
       public function getPreview(string $url, bool $forceRefresh = false): array
       {
           return LinkPreview::get($url, ['refresh' => $forceRefresh]);
       }
   
       public function getCachedPreview(string $url): ?array
       {
           return LinkPreview::get($url, ['cache_only' => true]);
       }
   }
   

2. Queue-Based Processing (for async operations):

   LinkPreview::get('https://slow-site.com')->queue();
   // Later, in a job:
   $preview = LinkPreview::getQueued('job-id')->get();
   

3. Platform-Specific Handling:

   $preview = LinkPreview::get('https://twitter.com/user/status/12345');
   if ($preview->type === 'twitter') {
       // Custom Twitter-specific UI
   }
   

Integration Tips

• Validation:

  use Teners\LinkPreview\Exceptions\PreviewException;
  
  try {
      $preview = LinkPreview::get($url);
  } catch (PreviewException $e) {
      // Handle invalid URLs or failed requests
  }
  

• Fallback Logic:

  $preview = LinkPreview::get($url, [
      'fallback' => [
          'title' => 'Untitled',
          'description' => 'No preview available',
          'image' => asset('fallback.png')
      ]
  ]);
  

• Custom Parsers: Extend the base parser for niche platforms:

  namespace App\Parsers;
  
  use Teners\LinkPreview\Contracts\ParserInterface;
  
  class CustomParser implements ParserInterface
  {
      public function parse(string $html, string $url): array
      {
          // Custom logic
      }
  }
  

  Register in config/link-preview.php:

  'parsers' => [
      'custom' => \App\Parsers\CustomParser::class,
  ],
  

Gotchas and Tips

Common Pitfalls

1. Caching Quirks:

   • Cache keys are generated from the URL + query string. Use LinkPreview::get($url, ['cache_key' => 'custom_key']) for consistent keys.
   • Clear cache manually with:

     LinkPreview::clearCache($url);
     // Or globally:
     LinkPreview::clearAllCache();
     

2. Rate Limiting:

   • Some platforms (e.g., Twitter) aggressively block scrapers. Use LinkPreview::get($url, ['delay' => 2]) to add delays between requests.

3. SSL Verification:

   • Disable for internal/self-signed URLs:

     LinkPreview::get($url, ['verify_ssl' => false]);
     

   • Warning: Only use this in development or trusted environments.

4. Redirect Handling:

   • Follow redirects by default, but disable with:

     LinkPreview::get($url, ['follow_redirects' => false]);
     

   • Useful for detecting malicious redirects.

5. Memory Limits:

   • Large HTML responses (e.g., news sites) may hit PHP memory limits. Adjust:

     LinkPreview::get($url, ['memory_limit' => '256M']);
     

Debugging Tips

• Enable Verbose Logging:

  LinkPreview::get($url, ['verbose' => true]);
  

  Check logs for raw HTTP responses and parsing steps.

• Inspect Raw HTML:

  $preview = LinkPreview::get($url, ['return_html' => true]);
  // $preview['html'] contains the raw response body
  

• Test with Known URLs: Use these for validation:

  // Twitter/X
  LinkPreview::get('https://twitter.com/TenersNet');
  
  // YouTube
  LinkPreview::get('https://youtube.com/watch?v=dQw4w9WgXcQ');
  
  // Generic HTML
  LinkPreview::get('https://example.com');
  

Extension Points

1. Custom Metadata Extraction: Override the default metadata parser:

   LinkPreview::get($url, [
       'metadata_parser' => function ($html) {
           // Return custom array of metadata
       }
   ]);
   

2. Event Listeners: Listen for preview events (e.g., preview.fetched):

   LinkPreview::get($url)->then(function ($preview) {
       // Post-processing
   });
   

3. Queue Monitoring: Check queued jobs:

   $queuedJobs = LinkPreview::queuedJobs();
   foreach ($queuedJobs as $job) {
       $job->refresh(); // Force refresh
   }
   

4. Performance Tuning:

   • Adjust timeout settings in config/link-preview.php:

     'timeout' => 10, // seconds
     'connect_timeout' => 5,
     

   • Use LinkPreview::get($url, ['timeout' => 30]) for slow sites.

5. Fallback Strategies: Implement a fallback chain:

   $preview = LinkPreview::get($url, [
       'fallbacks' => [
           'https://via.placeholder.com/150', // Image fallback
           'No description available',         // Description fallback
       ]
   ]);