Wkhtmltopdf Amd64 Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add the package via Composer:

   composer require h4cc/wkhtmltopdf-amd64
   

   Ensure your system meets wkhtmltopdf requirements (Linux amd64, Qt dependencies).

2. Basic Usage Inject the service provider in config/app.php:

   'providers' => [
       // ...
       H4cc\Wkhtmltopdf\WkhtmltopdfServiceProvider::class,
   ],
   

   Bind the facade (optional but recommended):

   'aliases' => [
       // ...
       'PDF' => H4cc\Wkhtmltopdf\Facades\PDF::class,
   ],
   

   OR Use the new static class (0.12.4+):

   use h4cc\WKHTMLToPDF;
   
   $pdf = WKHTMLToPDF::loadHTML('<h1>Hello World</h1>')->saveAs('output.pdf');
   

3. First PDF Generation

   use PDF;
   
   $pdf = PDF::loadView('pdf.template', ['data' => $yourData]);
   return $pdf->download('filename.pdf');
   

Implementation Patterns

Common Workflows

1. Generating PDFs from Views

   $pdf = PDF::loadView('invoices.invoice', ['invoice' => $invoice])
       ->setOption('margin-top', '20mm')
       ->setOption('margin-bottom', '20mm')
       ->save(storage_path('app/invoices/invoice_'.$invoice->id.'.pdf'));
   

2. Static Class Usage (New in 0.12.4)

   use h4cc\WKHTMLToPDF;
   
   $pdf = WKHTMLToPDF::loadHTML($htmlContent)
       ->setOption('quiet', '')
       ->saveAs('report.pdf');
   

3. Queueing PDF Jobs Use Laravel Queues to offload heavy PDF generation:

   dispatch(new GeneratePdfJob($userId, $template));
   

   Job class (works with both facade and static class):

   public function handle() {
       $pdf = PDF::loadView('user.profile', ['user' => User::find($this->userId)])
           ->save(storage_path("app/user_{$this->userId}.pdf"));
       // OR
       $pdf = WKHTMLToPDF::loadView('user.profile', ['user' => User::find($this->userId)])
           ->saveAs(storage_path("app/user_{$this->userId}.pdf"));
   }
   

4. Dynamic Options

   $pdf = PDF::loadHTML($html)
       ->setOption('orientation', 'Landscape')
       ->setOption('page-size', 'A4')
       ->setOption('encoding', 'UTF-8');
   

Integration Tips

• CSS/JS Support: Ensure compatibility with QtWebKit (avoid modern CSS features like flexbox or grid unless tested).
• Font Handling: Use system fonts or embed custom fonts via @font-face with wkhtmltopdf options:

  PDF::loadHTML($html)->setOption('font-name', 'Arial');
  

• Headers/Footers: Use header-html and footer-html options:

  PDF::loadView('invoice')
      ->setOption('header-html', view('pdf.header'))
      ->setOption('footer-html', view('pdf.footer'));
  

Gotchas and Tips

Pitfalls

1. Binary Compatibility

   • The package provides a pre-built amd64 binary (no source compilation). Ensure your server matches:

     uname -m  # Must return 'x86_64'
     

   • Fix: Use Docker or a compatible VPS if your server is ARM-based.

2. Missing Dependencies

   • wkhtmltopdf requires libxrender, libfontconfig, and libfreetype6. Install via:

     sudo apt-get install -y xfonts-75dpi xfonts-base libxrender1 libfontconfig1 libfreetype6
     

3. Memory Limits

   • Complex PDFs may hit PHP’s memory_limit. Increase in .env:

     MEMORY_LIMIT=2G
     

4. Headless Mode

   • wkhtmltopdf may fail silently if run without a display. Force headless mode:

     PDF::setOption('enable-local-file-access', '');
     

Debugging

• Check Binary Path Verify the binary path in config/wkhtmltopdf.php:

  'binary' => base_path('vendor/h4cc/wkhtmltopdf-amd64/bin/wkhtmltopdf'),
  

  If missing, symlink manually:

  ln -s vendor/h4cc/wkhtmltopdf-amd64/bin/wkhtmltopdf /usr/local/bin/wkhtmltopdf
  

• Log Errors Enable debug mode:

  PDF::setOption('debug-javascript', '');
  PDF::setOption('error-log', storage_path('logs/wkhtmltopdf.log'));
  

Extension Points

1. Custom Binary Override the binary path in config/wkhtmltopdf.php or via environment:

   WKHTMLTOPDF_BINARY=/custom/path/to/wkhtmltopdf
   

2. Post-Processing Use Laravel’s finished event to modify PDFs:

   PDF::loadView('report')->save($path)->finished(function ($path) {
       // Add watermark, compress, etc.
   });
   

3. Queue Failures Handle failed jobs with failed method:

   GeneratePdfJob::failed(function ($job, $exception) {
       Log::error("PDF generation failed: {$exception->getMessage()}");
   });
   

4. Static Class Usage (New in 0.12.4)

   • The new \h4cc\WKHTMLToPDF class provides a simpler, facade-free API.
   • Note: Methods like save() are replaced with saveAs() for clarity.
   • Migration Tip: Update calls from:

     PDF::loadHTML($html)->save($path);
     

     to:

     WKHTMLToPDF::loadHTML($html)->saveAs($path);