Php Puppeteer Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   • Follow the Ubuntu setup guide or use Docker for consistency.
   • Ensure Node.js 12+ and Chromium are installed globally:

     sudo npm install --global --unsafe-perm puppeteer
     

   • Verify with:

     puppeteer --version
     

2. Composer Install:

   composer require eckinox/php-puppeteer
   

3. First Use Case: Generate a PDF from a URL (e.g., a Laravel route for invoices):

   use Eckinox\PhpPuppeteer\Browser;
   
   $browser = new Browser();
   $pdfContent = $browser->pdf([
       'url' => 'https://example.com/invoice/123',
       'pdf' => ['format' => 'A4', 'margin' => '1cm']
   ]);
   
   return response($pdfContent, 200)->header('Content-Type', 'application/pdf');
   

4. Key Files to Review:

   • vendor/eckinox/php-puppeteer/src/Browser.php (core class).
   • examples/ in the repo for advanced use cases (e.g., cookies, page breaks).

Implementation Patterns

Core Workflows

1. Dynamic PDF Generation in Laravel

• Use Case: Generate invoices/reports with user-specific data.
• Pattern:

  // app/Services/PdfService.php
  class PdfService {
      public function generateInvoice($userData) {
          $html = view('invoices.pdf', compact('userData'))->render();
          $browser = new Browser();
          return $browser->pdf([
              'html' => $html,
              'pdf' => ['format' => 'A4', 'margin' => '1cm'],
              'viewport' => ['width' => 1280, 'height' => 800]
          ]);
      }
  }
  

• Integration:
  • Call from a Laravel controller or queue job.
  • Store PDFs in storage/app/pdf/ using Laravel’s filesystem.

2. Queue-Based Async Generation

• Use Case: Avoid blocking requests during PDF generation.
• Pattern:

  // app/Jobs/GeneratePdfJob.php
  class GeneratePdfJob implements ShouldQueue {
      use Dispatchable, InteractsWithQueue;
  
      public function handle() {
          $pdf = app(PdfService::class)->generateInvoice($this->userData);
          Storage::put("pdfs/{$this->filename}.pdf", $pdf);
      }
  }
  

• Dispatch:

  GeneratePdfJob::dispatch($userData, 'invoice_123.pdf')->onQueue('pdfs');
  

3. Reusing Chromium Instances

• Use Case: Optimize performance in high-traffic apps.
• Pattern:

  // app/Providers/AppServiceProvider.php
  public function boot() {
      $this->app->singleton(Browser::class, function () {
          return new Browser(['cacheDir' => storage_path('chromium-cache')]);
      });
  }
  

• Config:

  $browser = app(Browser::class);
  $pdf = $browser->pdf([...]);
  

4. Handling Authenticated Content

• Use Case: Generate PDFs for logged-in users (e.g., dashboards).
• Pattern:

  $browser = new Browser();
  $page = $browser->newPage();
  $page->setCookie([
      'name' => 'session',
      'value' => $user->apiToken,
      'domain' => 'example.com'
  ]);
  $pdf = $page->pdf(['url' => 'https://example.com/dashboard']);
  

Integration Tips

• Laravel Views: Use Blade templates for HTML, then pass to php-puppeteer:

  $html = view('report', ['data' => $reportData])->render();
  $pdf = $browser->pdf(['html' => $html]);
  

• API Endpoints: Expose PDF generation via Laravel routes:

  Route::post('/pdf/generate', function (Request $request) {
      $pdf = app(PdfService::class)->generateFromRequest($request);
      return response($pdf)->header('Content-Type', 'application/pdf');
  });
  

• Testing: Mock the Browser class in unit tests:

  $mockBrowser = Mockery::mock(Browser::class);
  $mockBrowser->shouldReceive('pdf')->andReturn('mock-pdf-content');
  $this->app->instance(Browser::class, $mockBrowser);
  

Gotchas and Tips

Pitfalls

1. Chromium Resource Usage:

   • Issue: Each Browser instance spawns a new Chromium process (~500MB RAM).
   • Fix: Reuse instances (singleton pattern) or limit concurrency with Laravel queues.

2. Headless Environment Failures:

   • Issue: Puppeteer may fail in CI/CD without GUI (e.g., GitHub Actions).
   • Fix: Use xvfb (Linux) or Docker with --no-sandbox:

     docker run --rm -e PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true -e PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser puppeteer/chromium
     

3. Font Loading Issues:

   • Issue: Custom fonts may not render in PDFs.
   • Fix: Use @font-face in CSS or preload fonts:

     $browser->pdf([
         'html' => '<link href="https://fonts.googleapis.com/css2?family=Roboto" rel="stylesheet">'.$html,
         'launchArgs' => ['--no-sandbox']
     ]);
     

4. URL/HTML Sanitization:

   • Issue: Malicious input (e.g., javascript: URLs) can exploit Puppeteer.
   • Fix: Sanitize HTML/URLs before passing to php-puppeteer:

     use Symfony\Component\DomCrawler\Crawler;
     $cleanHtml = (new Crawler($html))->html();
     

5. Deprecated PHP 5 Support:

   • Issue: Package claims PHP 5 compatibility but may break on PHP 7.4+.
   • Fix: Enforce PHP 7.2+ in composer.json:

     "config": {
         "platform": {
             "php": "7.4"
         }
     }
     

Debugging Tips

• Log Chromium Output: Add --log-level=debug to launchArgs to debug rendering issues:

  $browser = new Browser(['launchArgs' => ['--log-level=debug']]);
  

• Inspect Pages: Use Puppeteer’s page.screenshot() to debug layout issues:

  $page = $browser->newPage();
  $page->goto('https://example.com');
  $page->screenshot(['path' => 'debug.png']);
  

• Timeout Errors: Increase waitUntil in goto options for slow-loading pages:

  $browser->pdf([
      'url' => 'https://slow-site.com',
      'goto' => ['waitUntil' => 'networkidle2']
  ]);
  

Extension Points

1. Custom Puppeteer Options: Extend the Browser class to support additional Puppeteer features:

   class ExtendedBrowser extends Browser {
       public function screenshot(array $options = []) {
           $page = $this->newPage();
           return $page->screenshot($options);
       }
   }
   

2. Laravel Service Provider: Bind the Browser class to the container with custom configs:

   // app/Providers/PuppeteerServiceProvider.php
   public function register() {
       $this->app->bind(Browser::class, function () {
           return new Browser([
               'cacheDir' => storage_path('chromium-cache'),
               'launchArgs' => ['--no-sandbox', '--disable-setuid-sandbox']
           ]);
       });
   }
   

3. Queue Monitoring: Track failed PDF jobs in Laravel Horizon:

   // app/Jobs/GeneratePdfJob.php
   public function failed(Throwable $exception) {
       Log::error("PDF generation failed: " . $exception->getMessage());
   }
   

Configuration Quirks

• cacheDir: Set a persistent directory to avoid re-downloading Chromium:

  $browser = new Browser(['cacheDir' => storage_path('chromium-cache')]);
  

• launchArgs: Common flags for production:

  ['launchArgs' => [
      '--no-sandbox',
      '--disable-setuid-sandbox