Knp Snappy Laravel Package

Getting Started

1. Install the package and wkhtmltopdf: Run composer require knplabs/knp-snappy and ensure wkhtmltopdf (v0.12.x) is installed system-wide or via Composer (e.g., h4cc/wkhtmltopdf-amd64).
2. Basic usage: Instantiate the Pdf generator with the binary path and call getOutput() or generate():

   use Knp\Snappy\Pdf;
   $snappy = new Pdf('/usr/bin/wkhtmltopdf'); // or vendor path
   header('Content-Type: application/pdf');
   echo $snappy->getOutput('https://example.com');
   

3. First use case: Generate a PDF from a URL for easy sharing or archival—e.g., invoices, reports, or documentation snapshots.

Implementation Patterns

• Laravel Integration: Use the official barryvdh/laravel-snappy package for seamless service provider registration, config binding (config/snappy.php), and facade usage (SnappyPdf::loadView(...)).
• Batch generation: Pass an array of URLs or HTML strings to generateFromHtml() or getOutput() to merge multiple documents into one PDF.
• Dynamic content: Render Blade views into HTML, then convert:

  $html = view('reports.monthly', $data)->render();
  $snappy->generateFromHtml($html, storage_path('app/reports/monthly.pdf'));
  

• Headers/footers: Inject HTML for page-level headers/footers via header-html/footer-html options—ensure they’re valid standalone HTML with <!DOCTYPE>.
• Background jobs: Offload PDF generation to queue workers (e.g., Horizon) to avoid timeouts, especially for large documents.
• Caching: Use cache-dir option to avoid redundant rendering of identical HTML, or cache output files in storage for reuse.

Gotchas and Tips

• Missing X server errors: On headless servers, wkhtmltopdf ≥0.12.2 works without xvfb, but if stuck on older versions, use xvfb-run or upgrade binaries.
• Security risk: --enable-local-file-access is a major attack vector—only enable it with sanitized, trusted HTML and sandbox the process.
• PDF rendering quirks:
  • Tables breaking mid-row? Add page-break-inside:avoid to tr.
  • Transparent PNG backgrounds turn black? Upgrade wkhtmltopdf to ≥0.12.3-dev.
  • Accented characters garbled? Set encoding => 'utf-8' and ensure HTML <meta charset="UTF-8">.
• Debugging: Use setLogger() with a PSR-3 logger to log exact wkhtmltopdf commands and stderr output.
• Binary path issues: When using Composer-provided binaries (e.g., h4cc), verify paths in vendor/h4cc/.../bin/ and test with exec() manually.
• Footer/header localization: For non-ASCII characters (e.g., "Página"), set setlocale(LC_CTYPE, 'es_ES.UTF-8') before instantiation to fix escapeshellarg behavior.
• Exit codes: Handle RuntimeException with getError() to decode wkhtmltopdf-specific errors (e.g., code 1 often means file not found or invalid CSS).
• Laravel gotcha: In config/snappy.php, use absolute paths for binaries—even base_path('vendor/bin/wkhtmltopdf-amd64') may fail; prefer realpath() or __DIR__ . '/../../vendor/bin/...'.