Sidecar Browsershot Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require wnx/sidecar-browsershot spatie/browsershot hammerstone/sidecar
   

   Skip Chrome/Puppeteer installation for spatie/browsershot as this package handles it via Lambda.

2. Configure Sidecar Add BrowsershotFunction::class to config/sidecar.php:

   'functions' => [
       \Wnx\SidecarBrowsershot\Functions\BrowsershotFunction::class,
   ],
   

3. Deploy Lambda

   php artisan sidecar:deploy --activate
   

4. First Use Case Replace Browsershot with BrowsershotLambda in your code:

   use Wnx\SidecarBrowsershot\BrowsershotLambda;
   
   BrowsershotLambda::url('https://example.com')->save('screenshot.png');
   

Implementation Patterns

Core Workflows

1. URL/HTML to File

   // Direct save to local storage
   BrowsershotLambda::url('https://example.com')->save('output.pdf');
   
   // HTML string to PDF
   BrowsershotLambda::html('<h1>Test</h1>')->save('output.pdf');
   

2. S3 Integration

   // Read HTML from S3
   BrowsershotLambda::readHtmlFromS3('path/to/file.html')->save('output.pdf');
   
   // Save directly to S3
   BrowsershotLambda::url('https://example.com')->saveToS3('s3/path/output.pdf');
   

3. Image Manipulation

   BrowsershotLambda::url('https://example.com')
       ->windowSize(1920, 1080)
       ->fit(\Spatie\Image\Enums\Fit::Contain, 200, 200)
       ->save('resized.png');
   

Advanced Patterns

1. Warm Lambda Instances Configure in .env:

   SIDECAR_BROWSERSHOT_WARMING_INSTANCES=3
   

   Reduces cold-start latency for frequent use.

2. Custom Fonts Place fonts in resources/sidecar-browsershot/fonts/ and redeploy Lambda.

3. Error Handling

   try {
       BrowsershotLambda::url('https://example.com')->save('output.pdf');
   } catch (\Wnx\SidecarBrowsershot\Exceptions\SidecarBrowsershotException $e) {
       // Handle Lambda/Sidecar errors
   }
   

Gotchas and Tips

Pitfalls

1. Lambda Size Limits

   • Payload Size: Lambda requests are limited to 6MB for direct HTML/URL input. Workaround: Use readHtmlFromS3() for large files.
   • Response Size: Lambda responses are limited to 6MB for downloads. Workaround: Use saveToS3() for large outputs.

2. Cold Starts

   • First request after deployment may take 5-10 seconds due to Lambda initialization.
   • Mitigation: Enable warming (SIDECAR_BROWSERSHOT_WARMING_INSTANCES).

3. Image Manipulation on S3

   • fit() operations require downloading the image locally before re-uploading.
   • Tip: Cache manipulated images locally if performance is critical.

4. Font Loading

   • Custom fonts must be placed in resources/sidecar-browsershot/fonts/ before redeploying Lambda.
   • Debug Tip: Check Lambda logs for font registration errors.

Debugging

1. Lambda Logs Use AWS CloudWatch to inspect execution logs:

   php artisan sidecar:logs
   

2. Sidecar Events Enable Sidecar’s debug mode in .env:

   SIDECAR_DEBUG=true
   

3. Common Errors

   Error	Cause	Solution
   TimeoutException	Lambda timeout (default: 3s)	Increase timeout in sidecar.php or optimize payload.
   InvalidArgumentException	Unsupported format	Ensure output format is pdf, png, jpg, etc.
   S3PermissionError	Missing IAM permissions	Attach AmazonS3FullAccess to Sidecar’s execution role.

Extension Points

1. Custom Layers Override Chromium/Puppeteer layers in sidecar-browsershot.php:

   'layers' => [
       'arn:aws:lambda:us-east-1:123456789012:layer:custom-chrome:1',
   ],
   

2. Event Hooks Extend BrowsershotFunction to add pre/post-processing:

   class CustomBrowsershotFunction extends BrowsershotFunction {
       protected function beforeExecute(): void {
           // Add custom logic (e.g., logging, auth)
       }
   }
   

3. Testing Mock Lambda responses in tests:

   $this->mockSidecarResponse('output.pdf', file_get_contents('tests/fixtures/example.pdf'));