Image Optimizer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require joshembling/image-optimizer
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Joshembling\ImageOptimizer\ImageOptimizerServiceProvider"
   

2. First Use Case: Replace FileUpload with OptimizedFileUpload in your Filament form:

   use Joshembling\ImageOptimizer\Forms\Components\OptimizedFileUpload;
   
   OptimizedFileUpload::make('image')
       ->image()
       ->imageEditor()
       ->required();
   

3. Key Files to Review:

   • config/image-optimizer.php (optimization settings)
   • Joshembling\ImageOptimizer\Forms\Components\OptimizedFileUpload (core component)

Implementation Patterns

Core Workflow

1. Form Integration: Replace FileUpload with OptimizedFileUpload for automatic optimization during upload.

   OptimizedFileUpload::make('avatar')
       ->image()
       ->directory('avatars')
       ->maxSize(2048);
   

2. Spatie Media Library Integration: Use OptimizedMediaLibraryFileUpload for Spatie Media Library:

   OptimizedMediaLibraryFileUpload::make('gallery')
       ->collection('images')
       ->maxSize(5)
       ->image();
   

3. Custom Optimization: Override default settings via config or component methods:

   OptimizedFileUpload::make('hero_image')
       ->image()
       ->quality(80)
       ->width(1200)
       ->height(800);
   

4. Batch Processing: Optimize existing files post-install:

   use Joshembling\ImageOptimizer\Facades\ImageOptimizer;
   
   ImageOptimizer::optimizeDirectory(storage_path('app/public/old-images'));
   

Common Patterns

• Conditional Optimization:

  OptimizedFileUpload::make('document')
      ->image()
      ->onlyWhen(fn ($record) => $record->is_premium_user);
  

• Dynamic Directories:

  OptimizedFileUpload::make('profile_picture')
      ->directory(fn ($record) => "users/{$record->id}");
  

• Fallback to Original:

  OptimizedFileUpload::make('fallback_image')
      ->image()
      ->fallbackToOriginal(); // Disables optimization for this field
  

Gotchas and Tips

Pitfalls

1. Filament v4 Incompatibility:

   • Gotcha: Package is not compatible with Filament v4. Plan migration before upgrading.
   • Workaround: Fork the package or use alternative solutions like spatie/laravel-image-optimizer.

2. Performance Overhead:

   • Gotcha: Optimization adds CPU/memory usage during uploads. Test with large files.
   • Tip: Use --queue option for async processing:

     OptimizedFileUpload::make('large_image')->queueOptimization();
     

3. Spatie Media Library Conflicts:

   • Gotcha: If using SpatieMediaLibraryFileUpload, ensure OptimizedMediaLibraryFileUpload is used instead to avoid duplicate processing.
   • Fix: Remove old FileUpload components and replace with OptimizedMediaLibraryFileUpload.

4. Config Overrides:

   • Gotcha: Global config (config/image-optimizer.php) may override component-specific settings.
   • Tip: Use ->mergeConfigWith() to customize per-component:

     OptimizedFileUpload::make('custom')
         ->mergeConfigWith(['quality' => 75, 'width' => 1000]);
     

Debugging

• Log Optimization: Enable debug mode in config to log skipped/optimized files:

  'debug' => env('IMAGE_OPTIMIZER_DEBUG', false),
  

• Check Temporary Files: Optimized files are processed in storage/app/temp/. Verify files exist here if uploads fail silently.

Extension Points

1. Custom Optimizers: Register additional optimizers (e.g., for WebP):

   ImageOptimizer::extend('webp', function ($path) {
       // Custom WebP conversion logic
   });
   

2. Pre/Post Hooks: Use events to intercept optimization:

   event(new OptimizingImage($originalPath, $optimizedPath));
   

   Register listeners in EventServiceProvider:

   protected $listen = [
       'Joshembling\ImageOptimizer\Events\OptimizingImage' => [
           YourOptimizationListener::class,
       ],
   ];
   

3. Fallback Mechanisms: Implement custom fallback logic for unsupported formats:

   OptimizedFileUpload::make('unsupported')
       ->fallbackToOriginal()
       ->onUnsupportedFormat(function ($file) {
           // Handle unsupported formats (e.g., return a placeholder)
       });