Filament Croppie Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require michaeld555/filament-croppie
   php artisan filament-croppie:install
   

   This publishes the config (config/filament-croppie.php) and translations.

2. Basic Usage in a Filament Form: Add the field to a Filament form resource:

   use Michaeld555\FilamentCroppie\Fields\Croppie;
   
   Croppie::make('avatar')
       ->image()
       ->required(),
   

3. First Use Case:

   • Upload and crop an image for a user profile. The field handles both the UI and backend storage (if configured).

Implementation Patterns

Common Workflows

1. Basic Image Cropping:

   Croppie::make('thumbnail')
       ->image()
       ->width(200)
       ->height(200)
       ->aspectRatio(1),
   

   • width/height: Set fixed dimensions.
   • aspectRatio: Lock proportions (e.g., 4/3 for widescreen).

2. Dynamic Configuration: Use closures for runtime adjustments:

   Croppie::make('cover_image')
       ->image()
       ->width(fn () => $this->record->is_large ? 1200 : 800)
       ->height(600),
   

3. Integration with Storage: Pair with Filament\Forms\Components\FileUpload for multi-step workflows:

   $form->schema([
       FileUpload::make('temp_image'),
       Croppie::make('final_image')
           ->image()
           ->uploadFromField('temp_image'),
   ]);
   

4. Reusable Components: Extend the field for domain-specific logic:

   class ProductImageCroppie extends Croppie {
       protected string $view = 'filament-croppie::product-image';
       public function configure(): static {
           return $this->width(1024)->height(1024);
       }
   }
   

5. Validation: Combine with Filament’s validation rules:

   Croppie::make('logo')
       ->image()
       ->required()
       ->rules('mimes:jpeg,png|max:2048'),
   

Gotchas and Tips

Pitfalls

1. Missing Config:

   • Forgetting to publish the config (php artisan vendor:publish --tag="filament-croppie-config") may break modal behavior or default values.

2. Aspect Ratio Conflicts:

   • If width/height and aspectRatio are set, the field prioritizes the ratio. Omit one dimension to avoid unexpected cropping.

3. File Upload Paths:

   • Ensure the upload_path in config points to a writable directory. Default: storage/app/public/croppie.

4. JavaScript Conflicts:

   • Croppie.js may clash with other libraries using jQuery. Isolate usage with:

     Croppie::make('image')->view('filament-croppie::custom-view'),
     

     Then override the view to wrap Croppie in a no-conflict scope.

5. Large Files:

   • Cropping heavy images (e.g., >5MB) may time out. Add client-side compression:

     Croppie::make('hero_image')->compressQuality(0.7),
     

Debugging Tips

• Console Errors: Check browser console for Croppie.js initialization issues (e.g., missing data-url or data-viewbox attributes).
• Log Uploads: Add a handleUpload event listener to debug file paths:

  Croppie::make('image')->listen('handleUpload', fn ($path) => Log::info('Uploaded to:', $path));
  

• View Overrides: Extend the default Blade view (resources/views/vendor/filament-croppie/field.blade.php) to customize UI or add tooltips.

Extension Points

1. Custom Actions: Add buttons to the modal via the actions config:

   Croppie::make('image')->actions([
       'rotate' => 'Rotate 90°',
       'flip' => 'Flip Horizontally',
   ]);
   

2. Presets: Create preset configurations for reuse:

   config(['filament-croppie.presets.thumbnail' => [
       'width' => 300,
       'height' => 300,
       'aspectRatio' => 1,
   ]]);
   

   Then use:

   Croppie::make('thumbnail')->preset('thumbnail'),
   

3. Server-Side Processing: Hook into the saving event to process the cropped image before storage:

   Croppie::make('image')->listen('saving', fn ($record, $state) => {
       $image = Image::make($state['path'])->resize(800, 600);
       $image->save($state['path']);
   });