Browsershot Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: spatie/browsershot excels in converting dynamic HTML (including JS-rendered content) to static formats (PDF, images, or HTML strings). This aligns perfectly with common TPM needs for:
  • Document generation (invoices, reports, certificates).
  • Headless testing (screenshots for QA or analytics).
  • Dynamic content archiving (e.g., saving rendered SPAs or dashboards).
• Laravel Synergy: Leverages Laravel’s service container for dependency injection (e.g., Puppeteer binaries, config overrides) and integrates seamlessly with Laravel’s filesystem, queues, and jobs.
• Extensibility: Supports Puppeteer’s full API (e.g., evaluateOnNewDocument, custom headers, timeouts), enabling advanced use cases like:
  • Post-render manipulation (e.g., injecting CSS/JS via page.evaluate()).
  • Multi-page PDFs (using Puppeteer’s pdf() options).
  • Interactive testing (clicking elements, simulating user flows).

Integration Feasibility

• Dependencies:
  • Puppeteer: Requires Node.js (≥18.x) and Chrome/Chromium (≥113.0). Can be containerized (Docker) or managed via system packages (e.g., npm install -g puppeteer).
  • Poppler-utils: Needed for PDF text extraction (optional but useful for searchable PDFs).
  • PHP Extensions: None critical; only file_get_contents for local HTML files.
• Laravel Compatibility:
  • Works with Laravel 8+ (tested up to PHP 8.5).
  • Supports queueable jobs (e.g., Browsershot::url()->delay(60)->save()) for async rendering.
  • Integrates with Laravel’s filesystem (e.g., Storage::disk('s3')->put()).
• Alternatives Considered:
  • wkhtmltopdf: Lighter but lacks JS support.
  • Dompdf: Pure PHP but struggles with modern JS frameworks.
  • Puppeteer Sharp: Node.js-only; browsershot bridges this gap for PHP.

Technical Risk

Key Questions for TPM

1. Performance Requirements:
   • Will this run in batch mode (e.g., 100+ PDFs/hour)? If so, optimize with:
     • Reusable Chrome instances (via Browsershot::setNodeOptions()).
     • Queue workers with sleep() between jobs to avoid OOM.
   • Are dynamic timeouts needed (e.g., for slow JS-heavy pages)?
2. Security:
   • Are external URLs trusted? If not, use setBlockedRequests() to block untrusted domains.
   • Should sandboxing be enforced (e.g., --no-sandbox disabled in production)?
3. Output Quality:
   • Need high-fidelity screenshots? Use setChromePath() to specify a non-headless Chrome build.
   • Require searchable PDFs? Ensure poppler-utils is installed.
4. Deployment:
   • Will this run in serverless (e.g., AWS Lambda)? If so, use pre-built Puppeteer binaries (e.g., puppeteer-core).
   • Is Docker an option? Use spatie/browsershot with a multi-stage build to reduce image size.
5. Monitoring:
   • How will render failures be logged? Use throwOnRemoteConnectionError() and wrap calls in try-catch.
   • Need metrics (e.g., render time)? Extend the package with custom Puppeteer metrics.

Integration Approach

Stack Fit

Migration Path

1. Pilot Phase:
   • Start with local HTML files (e.g., Browsershot::htmlFromFilePath()) to test rendering.
   • Use simple URLs (e.g., static sites) to validate output quality.
2. Core Integration:
   • Service Provider: Bind config (e.g., chrome_path, node_options).

     $this->app->singleton(Browsershot::class, function ($app) {
         return Browsershot::withNodeOptions(['--no-sandbox'])
                           ->setChromePath('/usr/bin/google-chrome');
     });
     

   • Queue Jobs: Wrap rendering in a job for async processing.

     class GeneratePdfJob implements ShouldQueue {
         public function handle() {
             Browsershot::url($this->url)->save(storage_path('app/pdf.pdf'));
         }
     }
     

3. Advanced Features:
   • Dynamic Content: Use evaluate() to modify DOM before rendering.

     Browsershot::html($html)
         ->evaluate('document.querySelector(".hidden").style.display = "none"')
         ->save('output.pdf');
     

   • Multi-Page PDFs: Chain Browsershot calls with Puppeteer’s PDFOptions.

     $pdf = Browsershot::html($html1)->pdf();
     $pdf->merge(Browsershot::html($html2)->pdf());
     

Compatibility

• Laravel Versions: Tested on 8.0–11.x; PHP 8.1–8.5.
• Puppeteer Versions: Requires ≥23.0 (v5.x). Downgrade to v4.x for older Puppeteer.
• Operating Systems:
  • Linux: Best support (Docker recommended).
  • Windows: Use WSL or Docker; avoid --no-sandbox in production.
  • macOS: Native support but may need poppler-utils (brew install poppler).
• Edge Cases:
  • Localhost/Dev Environments: Use setAllowInsecureHttp(true) for Vite/HMR.
  • Cross-Origin Requests: Handle CORS with setExtraChromeFlags(['--disable-web-security']) (dev only).

Sequencing

1. Pre-requisites:
   • Install Node.js (≥18.x) and Chrome (≥113.0).
   • Add spatie/browsershot to composer.json:

     composer require spatie/browsershot
     

2. Configuration:
   • Publish config: php artisan vendor:publish --provider="Spatie\Browsershot\BrowsershotServiceProvider".
   • Customize