Filament Spatie Media Library Croppie Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require josefbehr/filament-spatie-media-library-croppie
   

   Ensure spatie/laravel-medialibrary and filament/spatie-laravel-media-library-plugin are also installed.

2. Publish Assets (if not using Filament’s built-in asset handling):

   npm run dev  # or `npm run build` for production
   

   Include the JS/CSS in your Vite/Mix config (as shown in README).

3. First Use Case: Add the field to a Filament resource form:

   use JosefBehr\FilamentSpatieMediaLibraryCroppie\Fields\SpatieMediaLibraryCroppie;
   
   SpatieMediaLibraryCroppie::make('avatar')
       ->label('Profile Image')
       ->imageEditor()
       ->required(),
   

Key Files to Review

• Field Class: SpatieMediaLibraryCroppie (extends Filament’s SpatieMediaLibrary).
• Configuration: Check config/filament-spatie-media-library-croppie.php (if published).
• Assets: resources/dist/js/filament-spatie-media-library-croppie.js (customize via Vite).

Implementation Patterns

Core Workflows

1. Basic Image Upload with Cropping:

   SpatieMediaLibraryCroppie::make('cover_image')
       ->imageEditor() // Enables Croppie.js
       ->directory('covers') // Optional: Custom media directory
       ->maxFiles(1)
       ->imageEditorAspectRatio('16:9'), // Lock aspect ratio
   

2. Dynamic Boundary Sizing: Use boundaryWidth/boundaryHeight to control the modal’s cropper dimensions:

   SpatieMediaLibraryCroppie::make('thumbnail')
       ->boundaryWidth('800px')
       ->boundaryHeight('400px'),
   

3. Integration with Existing Media Library: Leverage Spatie’s convertImage() or generateConversions() for post-upload processing:

   // In your model:
   public function registerMediaConversions(): void
   {
       $this->addMediaConversion('thumb')
           ->width(200)
           ->height(200);
   }
   

4. Conditional Field Logic: Combine with Filament’s visible()/rules():

   SpatieMediaLibraryCroppie::make('logo')
       ->visible(fn ($record) => $record->isPremiumUser())
       ->rules(['dimensions:min_width=1000,min_height=500']),
   

Advanced Patterns

• Custom Croppie.js Options: Override defaults via extraImageEditorOptions:

  ->extraImageEditorOptions([
      'viewZoom': 2,
      'enableOrientation': true,
  ]),
  

• Multi-File Uploads: Use maxFiles() and handle conversions in a saving() hook:

  ->maxFiles(5)
  ->saving(function ($record, $state) {
      foreach ($state as $media) {
          $media->registerMediaConversions();
      }
  }),
  

• Reusable Field Components: Create a trait or base field for consistency:

  trait UsesCroppieImageField
  {
      protected function configureCroppieField(string $name): SpatieMediaLibraryCroppie
      {
          return SpatieMediaLibraryCroppie::make($name)
              ->imageEditor()
              ->boundaryWidth('100%')
              ->boundaryHeight('500px');
      }
  }
  

Gotchas and Tips

Pitfalls

1. Asset Loading Issues:

   • Symptom: Croppie.js fails to load or styles are broken.
   • Fix: Ensure Vite/Mix includes the bundled JS/CSS after Filament’s core assets. Use @vite() in your blade template before </body>:

     @vite([
         'resources/js/app.js',
         'vendor/josefbehr/filament-spatie-media-library-croppie/resources/dist/js/filament-spatie-media-library-croppie.js',
     ])
     

2. CORS/Storage Errors:

   • Symptom: Uploads hang or return CORS errors.
   • Fix: Verify Spatie’s [media] disk configuration in .env matches your storage setup. For local testing, use:

     MEDIA_DRIVER=local
     

3. Aspect Ratio Conflicts:

   • Symptom: Cropped images appear distorted.
   • Fix: Explicitly set imageEditorAspectRatio() or disable it (->imageEditor(false)) if using server-side cropping.

4. Filament Version Mismatch:

   • Symptom: Field renders incorrectly or throws errors.
   • Fix: Check the package’s releases for Filament compatibility. As of writing, it targets Filament v2.x.

Debugging Tips

• Inspect Network Requests: Check the browser’s Network tab for failed uploads (look for 4xx/5xx responses to /filament-media-library endpoints).
• Log Media Events: Add a saving() hook to debug state:

  ->saving(function ($record, $state) {
      \Log::debug('Uploaded media:', $state);
  }),
  

• Clear Cached Views: After modifying JS/CSS, run:

  php artisan view:clear
  npm run dev
  

Extension Points

1. Custom Croppie Plugins: Extend Croppie’s functionality by modifying the bundled JS. Override the default file in resources/js/filament-spatie-media-library-croppie.js:

   // Add to the existing Croppie initialization:
   croppieInstance.bind({
       setDragCursor: true,
       setZoomCursor: true,
   });
   

2. Server-Side Cropping: Use Spatie’s convertImage() in a saved() hook for dynamic resizing:

   ->saved(function ($record, $state) {
       if ($state) {
           $record->media()->first()->convertImage('thumb');
       }
   }),
   

3. Localization: Override labels/placeholders via Filament’s translation system:

   ->label(__('filament-spatie-media-library-croppie::fields.spatie_media_library_croppie.label'))
   ->placeholder(__('filament-spatie-media-library-croppie::fields.spatie_media_library_croppie.placeholder')),
   

4. Testing: Mock the field in PHPUnit using Filament’s testing helpers:

   $this->filament()->fillForm([
       'spatie_media_library_croppie_field' => UploadedFile::fake()->image('test.jpg'),
   ]);