Pdf Manager Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require docdigital/pdf-manager
   

   Ensure dompdf/dompdf is also installed (dependency):

   composer require dompdf/dompdf
   

2. Basic Usage

   use DocDigital\PdfManager\PdfManager;
   
   $pdfManager = new PdfManager();
   $mergedPdf = $pdfManager->merge(['path/to/file1.pdf', 'path/to/file2.pdf']);
   $mergedPdf->save('merged_output.pdf');
   

3. First Use Case

   • Merging PDFs: Combine multiple PDFs into one.
   • Splitting PDFs: Extract specific pages from a PDF.
   • Generate PDFs from HTML: Use dompdf integration to create PDFs dynamically.

Where to Look First

• README: Focus on the Usage section for basic examples.
• Source Code: Explore src/PdfManager.php for core methods (merge, split, generateFromHtml).
• Tests: Check tests/ for edge cases and validation logic.

Implementation Patterns

Common Workflows

1. Merging PDFs

   $pdfManager = new PdfManager();
   $mergedPdf = $pdfManager->merge(['file1.pdf', 'file2.pdf']);
   $mergedPdf->save(storage_path('app/merged.pdf'));
   

   • Batch Processing: Loop through an array of files:

     $files = Storage::files('pdfs/to/merge');
     $merged = $pdfManager->merge($files);
     

2. Splitting PDFs

   $pdfManager->split('input.pdf', [1, 3, 5]) // Extract pages 1, 3, 5
               ->save('output_page1.pdf', 'output_page3.pdf', 'output_page5.pdf');
   

   • Page Ranges: Use ranges for efficiency:

     $pdfManager->split('input.pdf', [1, 3, '5-7']); // Pages 1, 3, and 5-7
     

3. Dynamic PDF Generation

   $html = '<h1>Hello, PDF!</h1><p>Generated via PdfManager.</p>';
   $pdf = $pdfManager->generateFromHtml($html);
   $pdf->save('dynamic.pdf');
   

   • Blade Templates: Pass Blade views:

     $pdf = $pdfManager->generateFromHtml(view('pdf.invoice', ['data' => $order]));
     

4. Integration with Laravel Storage

   use Illuminate\Support\Facades\Storage;
   
   $files = Storage::disk('s3')->files('pdfs');
   $merged = $pdfManager->merge($files);
   Storage::disk('s3')->put('merged.pdf', $merged->output());
   

Best Practices

• Error Handling: Wrap operations in try-catch for file operations:

  try {
      $pdfManager->merge($files)->save('output.pdf');
  } catch (\Exception $e) {
      Log::error("PDF merge failed: " . $e->getMessage());
  }
  

• Memory Management: For large PDFs, stream output directly to disk instead of holding in memory:

  $pdfManager->merge($files)->streamTo(storage_path('app/large.pdf'));
  

• Queue Jobs: Offload heavy operations to Laravel queues:

  MergePdfJob::dispatch($files, 'output.pdf')->onQueue('pdfs');
  

Gotchas and Tips

Pitfalls

1. File Paths

   • Issue: Relative paths may break in production.
   • Fix: Use absolute paths or Laravel’s storage_path()/public_path():

     $pdfManager->merge([storage_path('file1.pdf'), storage_path('file2.pdf')]);
     

2. Memory Limits

   • Issue: Merging large PDFs may hit PHP’s memory_limit.
   • Fix: Increase memory_limit in php.ini or stream output incrementally.

3. Dompdf Dependencies

   • Issue: Missing fonts or libraries may cause rendering errors.
   • Fix: Configure dompdf properly (see Dompdf docs).

4. Page Count Mismatch

   • Issue: split() may fail if page numbers exceed the PDF’s total pages.
   • Fix: Validate page counts first:

     $pageCount = $pdfManager->getPageCount('input.pdf');
     if (max($pagesToExtract) > $pageCount) {
         throw new \InvalidArgumentException("Page exceeds total pages.");
     }
     

5. Encoding Issues

   • Issue: Special characters in filenames may cause errors.
   • Fix: Sanitize filenames:

     $safePath = Str::slug('filename with spaces.pdf');
     

Debugging Tips

• Log Output: Enable Dompdf debugging:

  $pdfManager->setDompdfOption('isRemoteEnabled', true);
  $pdfManager->setDompdfOption('isHtml5ParserEnabled', true);
  

• Check Temp Files: Dompdf creates temporary files in /tmp. Verify permissions.
• Validate Input: Use file_exists() to confirm files before processing:

  $files = array_filter($files, 'file_exists');
  

Extension Points

1. Custom Dompdf Configuration Override default Dompdf settings:

   $pdfManager->setDompdfOption('defaultFont', 'DejaVu Sans');
   $pdfManager->setDompdfOption('isPhpEnabled', true);
   

2. Add Watermarks Extend the PdfManager class to add watermarks before merging:

   class WatermarkedPdfManager extends PdfManager {
       public function addWatermark($pdfContent, $watermarkText) {
           // Use TCPDF or Imagick to add watermark
           return $pdfContent;
       }
   }
   

3. Laravel Service Provider Bind PdfManager to the container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->singleton(PdfManager::class, function () {
           return new PdfManager();
       });
   }
   

4. Artisan Commands Create CLI tools for batch processing:

   // app/Console/Commands/MergePdfs.php
   public function handle() {
       $pdfManager = app(PdfManager::class);
       $merged = $pdfManager->merge($this->getFiles());
       $merged->save(storage_path('app/merged.pdf'));
   }