Laravel Pdf Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-pdf
   php artisan vendor:publish --provider="Spatie\Pdf\PdfServiceProvider" --tag="pdf-config"
   

   Configure your preferred driver in config/pdf.php (e.g., browsershot, dompdf, or gotenberg).

2. First Use Case: Generate a PDF from a Blade view in a controller:

   use Spatie\LaravelPdf\Facades\Pdf;
   
   public function generatePdf()
   {
       return Pdf::view('pdfs.invoice', ['data' => $data])
           ->name('invoice.pdf');
   }
   

3. Key Files:

   • config/pdf.php: Driver and default settings.
   • resources/views/pdfs/: Store Blade templates for PDFs.
   • app/Providers/AppServiceProvider.php: Register custom drivers if needed.

Implementation Patterns

Core Workflows

1. Dynamic PDF Generation: Use Blade views with dynamic data:

   Pdf::view('pdfs.report', ['users' => User::all()])
       ->format('a4')
       ->save(storage_path('app/reports/report.pdf'));
   

2. Conditional Formatting: Apply rules based on data:

   Pdf::view('pdfs.order', ['order' => $order])
       ->when($order->isUrgent(), fn ($pdf) => $pdf->margins(10))
       ->unless($order->isDigital(), fn ($pdf) => $pdf->headerView('pdfs.header'));
   

3. Reusable PDF Builders: Create a service class for complex PDFs:

   class InvoicePdfService {
       public function generate(Invoice $invoice) {
           return Pdf::view('pdfs.invoice', ['invoice' => $invoice])
               ->meta(title: "Invoice #{$invoice->id}")
               ->format('a4')
               ->name("invoice_{$invoice->id}.pdf");
       }
   }
   

4. Testing PDFs: Use the Pdf::fake() facade for unit tests:

   it('generates a PDF with correct content', function () {
       Pdf::fake();
       $response = $this->get('/pdf/invoice');
       Pdf::assertRespondedWithPdf(fn ($pdf) => $pdf->contains('Total'));
   });
   

Integration Tips

• Queue PDF Generation: Use Laravel queues to offload PDF generation:

  Pdf::view('pdfs.heavy-report', ['data' => $data])
      ->save(storage_path('app/reports/heavy-report.pdf'))
      ->dispatch(); // Dispatch to queue
  

• Custom Drivers: Extend the PdfDriver class for bespoke logic:

  class CustomDriver extends PdfDriver {
      public function generate($view, $data) {
          // Custom logic
          return parent::generate($view, $data);
      }
  }
  

• PDF Metadata: Set metadata dynamically:

  Pdf::view('pdfs.document', ['doc' => $doc])
      ->meta([
          'title' => "Document #{$doc->id}",
          'author' => $doc->user->name,
          'keywords' => 'document, ' . $doc->category,
      ]);
  

• Headers/Footers: Use shared Blade views for consistency:

  <!-- resources/views/pdfs/partials/footer.blade.php -->
  <footer>
      Page @pageNumber of @totalPages | {{ config('app.name') }}
  </footer>
  

  Pdf::view('pdfs.document', ['doc' => $doc])
      ->footerView('pdfs.partials.footer');
  

Gotchas and Tips

Pitfalls

1. Driver Compatibility:

   • DOMPDF: Limited CSS support (no Flexbox/Grid). Use for simple layouts.
   • Browsershot/Gotenberg: Require Chromium/Docker. Use for modern CSS.
   • Cloudflare: Network-dependent. Avoid in offline environments.

2. Image Paths: Absolute paths (e.g., https://example.com/logo.png) work in headers/footers, but relative paths (e.g., public_path('logo.png')) may fail. Use @inlinedImage:

   @inlinedImage(public_path('logo.png'))
   

3. Margins and Scaling:

   • Margins in mm by default. Use Unit::Pixel for pixel precision.
   • Scaling (->scale(0.75)) only works with Chromium-based drivers.

4. Page Ranges: Only supported by Browsershot/Cloudflare. DOMPDF ignores this.

5. Tagged PDFs: Only Browsershot/Cloudflare support accessibility features like ->tagged().

6. Memory Limits: Complex PDFs (e.g., large tables) may hit memory limits. Use ->scale() or simplify CSS.

Debugging

1. Inspect Builder State:

   Pdf::view('pdfs.document', ['doc' => $doc])
       ->dump(); // Dump current settings
   

2. Check Driver Logs: For Browsershot/Gotenberg, check Chromium logs or Docker logs for errors.

3. Validate HTML/CSS: Test Blade views in a browser first to ensure rendering works before PDF generation.

4. Fallback Drivers: Configure a fallback driver in config/pdf.php:

   'fallback' => 'dompdf',
   

Tips

1. Caching: Cache generated PDFs to avoid reprocessing:

   $path = storage_path("app/cache/invoice_{$invoice->id}.pdf");
   if (!file_exists($path)) {
       Pdf::view('pdfs.invoice', ['invoice' => $invoice])
           ->save($path);
   }
   return response()->file($path);
   

2. Dynamic Filenames: Use Str::slug() for safe filenames:

   ->name("invoice_{$invoice->id}_{$invoice->created_at->format('Y-m-d')}.pdf")
   

3. Local Testing: Use dompdf for local development (no external dependencies):

   'driver' => env('PDF_DRIVER', 'dompdf'),
   

4. Production Optimization: For Gotenberg/Browsershot, set ->timeout(30) to avoid hanging.

5. Laravel Boost: Run php artisan boost:install to enable AI-assisted PDF generation in IDEs.

6. Custom CSS: Reset default styles in PDF Blade views:

   <style>
       body { margin: 0; font-family: Arial; }
   </style>
   

7. Environment-Specific Drivers: Use .env to switch drivers:

   PDF_DRIVER=dompdf
   

   config(['pdf.driver' => env('PDF_DRIVER', 'browsershot')]);
   

8. PDF-to-Text Testing: Install poppler-utils (brew install poppler-utils) to verify text extraction:

   pdftotext path/to/generated.pdf