Pdf Optimizer Laravel Package

Getting Started

Minimal Setup

1. Install Ghostscript (required):

   # Ubuntu/Debian
   sudo apt-get install ghostscript
   
   # Alpine
   sudo apk add ghostscript
   
   # MacOS
   brew install ghostscript
   

2. Install the package:

   composer require mostafaznv/pdf-optimizer
   

3. Publish config (Laravel only):

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

First Use Case

Optimize a PDF file from disk to disk:

use Mostafaznv\PdfOptimizer\PdfOptimizer;

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

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

For Laravel, use the facade:

use Mostafaznv\PdfOptimizer\Laravel\Facade\PdfOptimizer;

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

Implementation Patterns

Core Workflow

1. Input Handling:

   • Local files: PdfOptimizer::init()->optimize('input.pdf', 'output.pdf')
   • Laravel disks: PdfOptimizer::fromDisk('s3')->open('input.pdf')->toDisk('local')
   • Uploaded files: Pass UploadedFile instance directly to open()

2. Method Chaining:

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

3. Queue Jobs (Laravel):

   PdfOptimizer::fromDisk('local')
       ->open('large.pdf')
       ->toDisk('s3')
       ->queue('optimize', 'output.pdf');
   

Integration Tips

• Pre-optimization hooks: Use beforeOptimize() callback for validation/logging.
• Post-optimization: Check $result->originalSize vs $result->optimizedSize for metrics.
• Batch processing: Loop through files in a directory and optimize in parallel using Laravel queues.

Common Use Cases

Gotchas and Tips

Pitfalls

1. Ghostscript Dependency:

   • Error: Ghostscript not found → Verify installation (gs --version).
   • Fix: Ensure binary is in PATH or configure custom path in .env:

     PDF_OPTIMIZER_GHOSTSCRIPT_BINARY=/custom/path/to/gs
     

2. Permission Issues:

   • Error: Permission denied when writing files.
   • Fix: Ensure Laravel storage disks (local, s3, etc.) have write permissions.

3. Memory Limits:

   • Large PDFs may hit PHP memory limits.
   • Fix: Increase memory_limit in php.ini or optimize in chunks.

4. Queue Failures:

   • Error: Jobs fail silently.
   • Fix: Enable logging:

     PdfOptimizer::init()->logger(new \Monolog\Logger('pdf_optimizer'));
     

Debugging

• Check logs: Enable verbose logging via:

  PdfOptimizer::init()->logger()->debug();
  

• Validate Ghostscript options: Use PdfOptimizer::init()->exportScript() to preview the generated command.
• Test locally: Run php artisan queue:work to debug failed jobs.

Configuration Quirks

• Default settings: Published config (config/pdf-optimizer.php) includes presets like SCREEN, PRINT, and EBOOK.
• Custom options: Use addGhostscriptOption() for unsupported features:

  ->addGhostscriptOption('-dPDFSETTINGS=/prepress')
  

Extension Points

1. Custom Optimizers:

   PdfOptimizer::init()->customOptimizer(function ($input, $output) {
       // Custom logic (e.g., pre-process with Imagick)
   });
   

2. Event Listeners:

   • Bind to PdfOptimizerOptimizing and PdfOptimizerOptimized events for hooks.

3. Service Provider:

   • Extend PdfOptimizerServiceProvider to add global defaults:

   PdfOptimizer::macro('customMacro', function () {
       return $this->settings(PdfSettings::EBOOK)->colorImageResolution(96);
   });
   

Performance Tips

• Batch processing: Use Laravel’s chunk() for large datasets.
• Cache results: Store optimized PDFs with a optimized_ prefix to avoid reprocessing.
• Monitor queue: Track job progress with PdfOptimizerJob events.

Laravel-Specific

• Disk fallbacks: Configure fallback_disk in config/filesystems.php for missing disks.
• Queue connections: Use queueOn('sqs') for distributed systems.
• Testing: Mock PdfOptimizer in tests:

  $this->partialMock(PdfOptimizer::class, ['optimize']);