Filament Media Manager Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require slimani/filament-media-manager
   php artisan vendor:publish --tag="media-manager-migrations"
   php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
   php artisan migrate
   php artisan vendor:publish --tag="media-manager-config"
   

2. Register Plugin: Add to your PanelProvider:

   public function panel(Panel $panel): Panel {
       return $panel->plugin(MediaManagerPlugin::make());
   }
   

3. First Use Case:

   • Create a model with InteractsWithMediaFiles trait.
   • Add a MediaPicker field to a Filament form:

     MediaPicker::make('avatar_id')
         ->relationship('avatar')
         ->label('User Avatar')
     

Implementation Patterns

Core Workflows

1. Model Integration:

   • Use InteractsWithMediaFiles for single/multiple file relationships.
   • Define relationships in your model (e.g., avatar(), documents()).
   • Example:

     public function avatar(): BelongsTo {
         return $this->mediaFile('avatar_id');
     }
     

2. Form Integration:

   • Single file selection:

     MediaPicker::make('avatar_id')
         ->relationship('avatar')
     

   • Multiple files:

     MediaPicker::make('documents')
         ->relationship('documents')
         ->multiple()
     

3. Table/Infolist Display:

   • Use MediaColumn for tables:

     MediaColumn::make('avatar')
         ->circular()
         ->stacked()
     

   • Use MediaImageEntry/MediaFileEntry for infolists:

     MediaImageEntry::make('avatar')
         ->circular()
         ->conversion('thumb')
     

4. Rich Text Integration:

   • Configure in setUpRichContent():

     $this->registerRichContent('resume')
         ->plugins([
             MediaManagerRichContentPlugin::make()
                 ->collection('preview')
                 ->directory('User/Resumes'),
         ]);
     

   • Use in forms:

     RichEditor::make('resume')
         ->plugins([
             MediaManagerRichContentPlugin::make(),
         ])
     

5. Folder/Tag Management:

   • Organize files via the Media Manager UI (folder hierarchy, tags).
   • Filter media in pickers using:

     MediaPicker::make('avatar_id')
         ->directory('User/Avatars')
         ->tags(['profile'])
     

Integration Tips

• Disk Configuration: Set default disk in config/media-manager.php or per-field:

  MediaPicker::make('avatar_id')
      ->disk('s3')
  

• Custom Conversions: Extend Spatie’s conversions via AppServiceProvider:

  File::registerMediaConversionsUsing(function (File $file) {
      $file->addMediaConversion('custom')
          ->width(1000)
          ->height(1000);
  });
  

• Permissions: Use Filament’s built-in policies to restrict access:

  MediaManagerPlugin::make()
      ->shouldRegisterNavigation(fn () => auth()->user()->can('manage-media'))
  

Gotchas and Tips

Pitfalls

1. Missing Migrations:

   • Forgetting to run php artisan migrate after publishing migrations will break file relationships.
   • Fix: Always run migrations post-installation.

2. Incorrect Relationships:

   • Using MediaPicker without defining the relationship in the model throws errors.
   • Fix: Ensure mediaFile() or mediaFiles() methods match the field name.

3. FFMPEG for Videos:

   • Video thumbnails require php-ffmpeg/php-ffmpeg and server-side FFMPEG/FFProbe.
   • Fix: Install the package and configure Spatie’s video processing.

4. Tailwind Styling:

   • Custom themes must include both @import and @source directives for styles/utility classes.
   • Fix: Add to theme.css as per the README.

5. Signed URLs:

   • Temporary URLs (e.g., S3) expire. Use renderRichContent() in infolists to regenerate URLs dynamically:

     TextEntry::make('resume')
         ->html()
         ->state(fn ($record) => $record->renderRichContent('resume'))
     

Debugging

• Media Not Loading:
  • Check disk configuration (config/filesystems.php) and permissions.
  • Verify the media_files table has entries for uploaded files.
• Picker Modal Blank:
  • Ensure the model uses InteractsWithMediaFiles and relationships are correctly defined.
  • Clear Filament cache (php artisan filament:cache:clear).

Extension Points

1. Custom Actions:
   • Extend the Media Manager’s table actions via Filament’s Table builder:

     MediaManagerPlugin::make()
         ->tableActions([
             Action::make('customAction')
                 ->action(fn (File $record) => /* logic */),
         ]);
     

2. Override Views:
   • Publish views and modify them:

     php artisan vendor:publish --tag="media-manager-views"
     

3. Event Listeners:
   • Listen to Spatie’s media events (e.g., MediaWasAdded) for custom logic:

     Event::listen(MediaWasAdded::class, function (MediaWasAdded $event) {
         // Custom logic on upload
     });
     

4. API Endpoints:
   • Use Filament’s API resources to expose media endpoints:

     ApiResource::make(File::class, 'api/files')
         ->navigationIcon('heroicon-o-photo')
         ->navigationGroup('Media');
     

Pro Tips

• Bulk Operations: Leverage Filament’s bulk actions for media:

  MediaManagerPlugin::make()
      ->tableActions([
          Tables\Actions\DeleteBulkAction::make(),
          Tables\Actions\ForceDeleteBulkAction::make(),
      ]);
  

• Lazy Loading: Optimize performance by lazy-loading media in tables/infolists:

  MediaColumn::make('avatar')
      ->lazy()
  

• Localization: Translate UI strings via Filament’s localization system:

  MediaPicker::make('avatar_id')
      ->label(__('filament-media-manager::media.avatar'))