Laravel Screenshot Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-screenshot
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\Screenshot\ScreenshotServiceProvider"
   

2. First Use Case: Capture a screenshot of a URL (e.g., a marketing page or dynamic content):

   use Spatie\Screenshot\Screenshot;
   
   $screenshot = Screenshot::create('https://example.com')->save('path/to/screenshot.png');
   

   • Default driver: browsershot (Chromium-based, local).
   • Cloudflare driver: Requires API token (configured in .env).

3. Where to Look First:

   • README: Quickstart and driver options.
   • Config: Adjust viewport, device scale, or timeout.
   • Testing: Example use cases (e.g., ScreenshotTest).

Implementation Patterns

Core Workflows

1. Dynamic Screenshots:

   • Capture Laravel routes/views on-the-fly:

     $screenshot = Screenshot::create(route('dashboard'))
         ->setDriver('browsershot')
         ->setViewport(1920, 1080)
         ->save(storage_path('app/screenshots/dashboard.png'));
     

   • Use Case: Generate thumbnails for SEO previews or user-generated content.

2. Batch Processing:

   • Queue screenshots for async execution (e.g., after content updates):

     $urls = ['https://site1.com', 'https://site2.com'];
     foreach ($urls as $url) {
         Screenshot::create($url)->queue();
     }
     

   • Tip: Use Spatie\QueueableScreenshot for queueable jobs.

3. Cloudflare Integration:

   • Offload heavy rendering to Cloudflare:

     config(['screenshot.driver' => 'cloudflare']);
     $screenshot = Screenshot::create('https://example.com')->save('cloud_screenshot.png');
     

   • Prerequisite: Set CLOUDFLARE_API_TOKEN in .env.

4. Custom Headers/Cookies:

   • Mimic authenticated requests:

     $screenshot = Screenshot::create('https://app.example.com/dashboard')
         ->setHeaders(['Authorization' => 'Bearer token123'])
         ->setCookies(['session_id' => 'abc123']);
     

Integration Tips

• Storage: Use Spatie\Screenshot\Storage\Disk to save to custom paths (e.g., S3):

  $screenshot->save('s3://bucket/screenshots/image.png');
  

• Events: Listen for ScreenshotCreated events to process screenshots post-capture:

  Screenshot::created(function ($screenshot) {
      // Optimize, upload, or notify
  });
  

• Testing: Mock drivers in unit tests:

  $this->partialMock(Screenshot::class, 'createDriver')->willReturn($mockDriver);
  

Gotchas and Tips

Pitfalls

1. Resource Limits:

   • Browsershot: Chromium may crash on complex pages (e.g., infinite scroll). Increase timeout:

     Screenshot::create(url)->setTimeout(60); // 60 seconds
     

   • Cloudflare: Free tier has rate limits. Cache results aggressively.

2. Dynamic Content:

   • JavaScript-heavy pages may fail. Use waitForSelector:

     $screenshot->waitForSelector('#dynamic-content');
     

   • Debug: Check logs for puppeteer errors (Browsershot under the hood).

3. Configuration Overrides:

   • Global config (e.g., viewport) applies to all screenshots. Override per instance:

     Screenshot::create(url)->setViewport(1024, 768);
     

4. Driver-Specific Quirks:

   • Browsershot: Requires Chromium installed. Use Docker if local setup is problematic.
   • Cloudflare: API token must have Browser Rendering permissions.

Debugging

• Logs: Enable verbose output:

  config(['screenshot.log_level' => 'debug']);
  

• Inspect HTML: Use getHtml() to debug rendering issues:

  $html = Screenshot::create(url)->getHtml();
  dd($html); // Check for missing JS/CSS
  

• Network Errors: Validate URLs/headers with curl or Postman before using the package.

Extension Points

1. Custom Drivers:

   • Implement Spatie\Screenshot\Contracts\Driver for new backends (e.g., Playwright):

     class PlaywrightDriver implements Driver {
         public function capture(string $url, array $options): string { ... }
     }
     

   • Register in config/screenshot.php:

     'drivers' => [
         'playwright' => \App\Drivers\PlaywrightDriver::class,
     ],
     

2. Middleware:

   • Add headers/cookies globally via middleware:

     Screenshot::middleware(function ($request) {
         $request->headers->set('X-Custom-Header', 'value');
     });
     

3. Post-Processing:

   • Chain with image libraries (e.g., Intervention) to resize/crop:

     use Intervention\Image\Facades\Image;
     
     $image = Image::make($screenshot->getPath());
     $image->resize(300, 200)->save();