Sidecar Browsershot Laravel Package

Technical Evaluation

Architecture Fit

• Serverless-First Design: The package leverages AWS Lambda via Sidecar, aligning with serverless architectures where compute resources are ephemeral and scalable. This is ideal for Laravel applications needing dynamic PDF/image generation without maintaining persistent infrastructure.
• Decoupled Heavy Lifting: Offloads resource-intensive tasks (Chromium/Puppeteer) to Lambda, reducing server load and improving performance for high-traffic applications.
• Event-Driven Potential: Can integrate with Laravel queues (e.g., sidecar:dispatch) for async processing, enabling scalability for batch operations (e.g., generating reports).

Integration Feasibility

• Laravel Native: Designed for Laravel with minimal friction—replaces spatie/browsershot with a Lambda-powered alternative. Uses Laravel’s service container and Artisan commands (sidecar:deploy).
• Sidecar Dependency: Requires hammerstone/sidecar (v2.0+), which must be configured for AWS Lambda. Adds complexity but provides a robust serverless abstraction.
• Browsershot Compatibility: Mimics spatie/browsershot API, enabling drop-in replacement for existing codebases. Supports v5+ (as of v2.5.0).

Technical Risk

• Cold Starts: Lambda cold starts (~100–500ms) may impact latency-sensitive workflows. Mitigated by:
  • Warming: Configurable via SIDECAR_BROWSERSHOT_WARMING_INSTANCES.
  • Provisioned Concurrency: Can be enabled in AWS Lambda for critical paths.
• Payload Limits: Lambda payload size (6MB) restricts large HTML/PDF inputs. Workarounds:
  • S3 Offloading: Stream inputs/outputs via S3 (supported natively).
  • Chunking: For very large files, implement client-side splitting.
• Dependency Lock-in: Tied to Sidecar’s AWS Lambda implementation. Migration to other serverless providers (e.g., Vercel Edge Functions) would require refactoring.
• Image Manipulation: Requires spatie/image for advanced features (e.g., fit()), adding optional dependencies.

Key Questions

1. Performance Requirements:
   • Are cold starts acceptable, or is provisioned concurrency justified?
   • What’s the expected throughput (requests/sec) for PDF/image generation?
2. Cost Analysis:
   • Lambda costs for warm instances vs. traditional server hosting (e.g., EC2 with pre-installed Chrome).
   • Data transfer costs for S3 usage (if offloading inputs/outputs).
3. Security:
   • Are Lambda execution roles properly scoped for S3 access (if using saveToS3)?
   • How will custom fonts be secured (e.g., avoiding exposure in Lambda layers)?
4. Monitoring:
   • How will Lambda errors (e.g., timeouts, memory limits) be logged/alerted?
   • Are there plans for distributed tracing (e.g., X-Ray integration)?
5. Upgrade Path:
   • How will the team handle Sidecar/Browsershot version upgrades (e.g., Chromium updates)?
   • Is there a rollback strategy for breaking changes (e.g., v3.0.0’s Chromium upgrade)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Core: Works with Laravel 11–13 (PHP 8.1–8.5). Drop-in replacement for spatie/browsershot.
  • Queues: Integrates with Laravel queues for async processing (e.g., sidecar:dispatch).
  • Filesystems: Supports S3 disks for input/output (requires aws disk config).
• AWS Services:
  • Lambda: Hosts Chromium/Puppeteer execution.
  • S3: Recommended for large files (inputs/outputs).
  • IAM: Requires execution role with Lambda/S3 permissions.
• Optional Dependencies:
  • spatie/image: For advanced image manipulation (e.g., resizing).
  • spatie/browsershot: Core dependency (v5+).

Migration Path

1. Prerequisites:
   • Install hammerstone/sidecar and configure AWS credentials (sidecar:configure).
   • Set up an S3 bucket for large files (if needed).
2. Installation:

   composer require wnx/sidecar-browsershot spatie/browsershot
   php artisan vendor:publish --tag="sidecar-browsershot-config"
   

3. Configuration:
   • Register BrowsershotFunction in sidecar.php:

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

   • Configure S3 disk in filesystems.php (if using saveToS3).
4. Deployment:

   php artisan sidecar:deploy --activate
   

5. Code Changes:
   • Replace Browsershot::url() with BrowsershotLambda::url().
   • Example:

     // Before
     Browsershot::url('https://example.com')->save('file.pdf');
     
     // After
     BrowsershotLambda::url('https://example.com')->saveToS3('file.pdf');
     

6. Testing:
   • Deploy a test Lambda function (sidecar-browsershot:setup).
   • Validate with existing Browsershot test cases.

Compatibility

• API Parity: Supports all spatie/browsershot methods (e.g., windowSize(), pdf(), bodyHtml()).
• Limitations:
  • No local file system access (use S3 for large files).
  • Image manipulation requires spatie/image (downloads to local disk temporarily).
• Breaking Changes:
  • Dropped support for Browsershot v4 (v2.8.0+).
  • Chromium layer updates may require redeployment (e.g., v3.0.0’s Chromium v147).

Sequencing

1. Phase 1: Non-Critical Paths
   • Start with low-priority PDF generation (e.g., admin reports).
   • Monitor Lambda costs/performance.
2. Phase 2: High-Traffic Endpoints
   • Migrate user-facing features (e.g., invoice generation).
   • Implement warming for critical paths.
3. Phase 3: Advanced Features
   • Add spatie/image for image manipulation.
   • Optimize S3 usage (e.g., lifecycle policies for old files).

Operational Impact

Maintenance

• Lambda Management:
  • Deployments: Redeploy Lambda on Sidecar/Browsershot updates (automate via CI/CD).
  • Layers: Monitor for security patches (e.g., Chromium updates in sidecar-browsershot-layer).
  • Configuration: Centralize sidecar-browsershot.php and sidecar.php in version control.
• Dependency Updates:
  • Watch for breaking changes in spatie/browsershot or Sidecar.
  • Test upgrades in staging before production.
• Custom Fonts:
  • Maintain resources/sidecar-browsershot/fonts folder.
  • Redeploy Lambda after font additions/updates.

Support

• Troubleshooting:
  • Cold Starts: Use CloudWatch logs to diagnose initialization delays.
  • Payload Errors: Check Lambda logs for PayloadTooLarge errors (switch to S3).
  • Permission Issues: Verify IAM roles for S3 access (if using saveToS3).
• Fallback Strategy:
  • Keep a fallback to local Browsershot (e.g., via feature flags) during outages.
  • Cache generated files locally to reduce Lambda calls.
• Documentation:
  • Update runbooks for:
    • Lambda timeout/memory configuration.
    • S3 bucket permissions.
    • Custom font deployment.

Scaling

• Horizontal Scaling:
  • Lambda auto-scales, but monitor concurrency limits (default: 1,000).
  • Adjust reserved_concurrent_executions if needed.
• Performance Tuning:
  • Warming: Set SIDECAR_BROWSERSHOT_WARMING_INSTANCES (e.g., 3–5) for low-latency needs.
  • Memory: Allocate 1GB–3GB RAM in Lambda (default: 128MB may be insufficient).
  • Timeout: Increase Lambda timeout (e.g., 30s) for complex pages.
• Cost Optimization:
  • Use ARM/Graviton2 processors (20% cheaper, better performance).
  • Schedule warming during off-peak hours if cost-sensitive.

Failure Modes