Pdf Optimizer Laravel Package

Getting Started

Minimal Setup

1. Install Ghostscript (system requirement):

   # Ubuntu/Debian
   sudo apt update && sudo apt-get install ghostscript
   

   Verify installation:

   gs --version
   

2. Install the package via Composer:

   composer require mostafaznv/pdf-optimizer
   

3. Publish Laravel config (if using Laravel):

   php artisan vendor:publish --provider="Mostafaznv\PdfOptimizer\PdfOptimizerServiceProvider"
   

First Use Case: Optimize a PDF File

// Standalone PHP
use Mostafaznv\PdfOptimizer\PdfOptimizer;

$result = PdfOptimizer::init()
    ->settings(\Mostafaznv\PdfOptimizer\Enums\PdfSettings::SCREEN)
    ->optimize('input.pdf', 'output.pdf');

if ($result->status) {
    echo "Optimized successfully!";
}

// Laravel (using Facade)
use Mostafaznv\PdfOptimizer\Laravel\Facade\PdfOptimizer;

$result = PdfOptimizer::fromDisk('local')
    ->open('input.pdf')
    ->toDisk('s3')
    ->optimize('output.pdf');

Implementation Patterns

Core Workflows

1. Basic Optimization

   PdfOptimizer::init()
       ->settings(PdfSettings::PRINT) // or SCREEN, ebook, etc.
       ->optimize('input.pdf', 'output.pdf');
   

2. Laravel Disk Integration

   PdfOptimizer::fromDisk('s3')
       ->open('large-file.pdf')
       ->toDisk('local')
       ->optimize('optimized.pdf');
   

3. Queue-Based Processing

   // Dispatch a job
   OptimizePdfJob::dispatch('input.pdf', 'output.pdf', [
       'settings' => PdfSettings::SCREEN,
       'resolution' => 72,
   ]);
   
   // Job class
   public function handle() {
       $result = PdfOptimizer::init()
           ->settings($this->settings)
           ->colorImageResolution($this->resolution)
           ->optimize($this->input, $this->output);
   }
   

Common Patterns

• Method Chaining: Chain settings for granular control:

  PdfOptimizer::init()
      ->settings(PdfSettings::SCREEN)
      ->colorImageResolution(90)
      ->grayImageResolution(150)
      ->embedAllFonts()
      ->optimize('input.pdf', 'output.pdf');
  

• UploadedFile Support:

  $result = PdfOptimizer::init()
      ->fromUploadedFile($request->file('pdf'))
      ->optimize('optimized.pdf');
  

• Custom Ghostscript Options:

  PdfOptimizer::init()
      ->addGhostscriptOption('-dNOPAUSE')
      ->addGhostscriptOption('-dBATCH')
      ->optimize('input.pdf', 'output.pdf');
  

Integration Tips

• Validation: Always validate $result->status before proceeding.
• Error Handling: Log $result->message for debugging:

  if (!$result->status) {
      Log::error('PDF Optimization Failed: ' . $result->message);
  }
  

• File Size Comparison: Use Laravel’s Storage facade to compare sizes:

  $originalSize = Storage::disk('local')->size('input.pdf');
  $optimizedSize = Storage::disk('local')->size('output.pdf');
  

Gotchas and Tips

Pitfalls

1. Ghostscript Not Found

   • Error: Ghostscript binary not found.
   • Fix: Ensure Ghostscript is installed and the binary path is correct (check config/pdf-optimizer.php).
   • Debug: Run which gs (Linux/Mac) or check PATH in Windows.

2. Permission Issues

   • Error: Failed to write output file.
   • Fix: Ensure the web server user (e.g., www-data) has write permissions to the output directory.

3. Memory Limits

   • Error: Ghostscript exited with code 1.
   • Fix: Increase PHP’s memory_limit or optimize with lower resolutions:

     ->colorImageResolution(72)
     ->grayImageResolution(72)
     

4. Windows Compatibility

   • Gotcha: The package is primarily tested on Unix-like systems.
   • Workaround: Use WSL or Docker for Windows deployments.

5. AGPL License Compliance

   • Gotcha: Ghostscript’s AGPL license may require compliance if your app is open-source.
   • Tip: Use a commercial license if distributing AGPL-incompatible software.

Debugging Tips

• Enable Logging:

  PdfOptimizer::init()
      ->enableLogging()
      ->optimize('input.pdf', 'output.pdf');
  

  Logs appear in storage/logs/laravel.log.

• Dry Run: Use exportScript() to generate the Ghostscript command for manual testing:

  $command = PdfOptimizer::init()
      ->settings(PdfSettings::SCREEN)
      ->exportScript('input.pdf', 'output.pdf');
  echo $command; // Copy and run manually
  

• Timeout Handling: Set a timeout to prevent hanging:

  PdfOptimizer::init()
      ->timeout(30) // 30 seconds
      ->optimize('input.pdf', 'output.pdf');
  

Extension Points

1. Custom Settings: Extend the PdfSettings enum or create a custom enum for project-specific presets:

   class AppPdfSettings {
       public const CUSTOM = 'custom-preset';
   }
   

2. Queue Job Customization: Override the default job class (OptimizePdfJob) for additional logic:

   class CustomOptimizePdfJob extends OptimizePdfJob {
       public function handle() {
           // Pre-processing logic
           parent::handle();
           // Post-processing logic
       }
   }
   

3. Logger Integration: Bind a custom logger in Laravel’s AppServiceProvider:

   PdfOptimizer::setLogger(app(\Psr\Log\LoggerInterface::class));
   

4. Ghostscript Binary Override: Dynamically set the binary path in config or runtime:

   PdfOptimizer::init()
       ->ghostscriptBinary('/custom/path/to/gs')
       ->optimize('input.pdf', 'output.pdf');
   

Performance Tips

• Batch Processing: Use Laravel queues to process multiple PDFs asynchronously:

  foreach ($pdfFiles as $file) {
      OptimizePdfJob::dispatch($file)->onQueue('optimize-pdfs');
  }
  

• Preset Optimization Profiles: Create reusable presets in a config file:

  // config/pdf-optimizer.php
  'presets' => [
      'low_quality' => [
          'settings' => PdfSettings::SCREEN,
          'color_resolution' => 60,
          'gray_resolution' => 72,
      ],
      'high_quality' => [
          'settings' => PdfSettings::PRINT,
          'color_resolution' => 150,
          'gray_resolution' => 150,
      ],
  ],
  

  Then apply them:

  PdfOptimizer::init()
      ->applyPreset('low_quality')
      ->optimize('input.pdf', 'output.pdf');