Spatie Laravel Media Library Plugin Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require filament/spatie-laravel-media-library-plugin
   

   Publish the plugin assets and config:

   php artisan vendor:publish --provider="Filament\SpatieMediaLibraryPlugin\SpatieMediaLibraryPluginServiceProvider"
   

2. Configure Media Library Ensure spatie/laravel-medialibrary is installed and configured in your Laravel app. Run:

   php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider"
   

   Configure your model to use the trait:

   use Spatie\MediaLibrary\HasMedia;
   use Spatie\MediaLibrary\InteractsWithMedia;
   
   class Post extends Model
   {
       use HasMedia, InteractsWithMedia;
   }
   

3. Register the Plugin Add the plugin to your Filament admin panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Filament\SpatieMediaLibraryPlugin::make(),
           ]);
   }
   

4. First Use Case Attach a media field to a Filament resource:

   use Filament\Forms\Components\SpatieMediaLibraryFileUpload;
   
   public static function form(Form $form): Form
   {
       return $form->schema([
           SpatieMediaLibraryFileUpload::make('image')
               ->collection('images')
               ->image()
               ->required(),
       ]);
   }
   

Implementation Patterns

Usage Patterns

1. Media Collections Define collections in your model to organize media:

   class Post extends Model
   {
       use HasMedia, InteractsWithMedia;
   
       public function registerMediaCollections(): void
       {
           $this->addMediaCollection('images');
           $this->addMediaCollection('documents');
       }
   }
   

2. Field Configuration Customize media upload fields in Filament resources:

   SpatieMediaLibraryFileUpload::make('thumbnail')
       ->collection('images')
       ->image()
       ->directory('thumbnails')
       ->openable()
       ->required()
       ->maxSize(2048) // 2MB
       ->imageResizeMode('cover')
       ->imageResizeTargetWidth(300)
       ->imageResizeTargetHeight(300),
   

3. Table Display Show media in Filament tables:

   use Filament\Tables\Columns\SpatieMediaLibraryImageColumn;
   
   public static function table(Table $table): Table
   {
       return $table->columns([
           SpatieMediaLibraryImageColumn::make('image')
               ->collection('images')
               ->width(50)
               ->height(50),
       ]);
   }
   

4. Bulk Actions Add bulk actions to manage media:

   public static function table(Table $table): Table
   {
       return $table->columns([
           // ...
       ])->actions([
           Tables\Actions\DeleteAction::make(),
       ])->bulkActions([
           Tables\Actions\BulkActionGroup::make([
               Tables\Actions\DeleteBulkAction::make(),
               SpatieMediaLibraryBulkDeleteAction::make(),
           ]),
       ]);
   }
   

Workflows

1. Media Upload Workflow

   • Use SpatieMediaLibraryFileUpload in forms for drag-and-drop uploads.
   • Validate file types, sizes, and dimensions upfront.
   • Process media after upload (e.g., generate thumbnails, run AI analysis).

2. Media Management Workflow

   • Use the plugin’s built-in media manager panel (/admin/media-library).
   • Filter, sort, and bulk-edit media directly from Filament.
   • Integrate with existing workflows (e.g., trigger actions when media is added).

3. Integration with Existing Media

   • Migrate existing media to the new system using Media::addRemoteMedia().
   • Sync old media records with the new collections.

Integration Tips

1. Custom Disk Configuration Override the default disk in the plugin config (config/filament-spatie-media-library.php):

   'disk' => 's3',
   

2. Custom Thumbnail Generators Extend the plugin’s thumbnail logic by publishing and overriding views:

   php artisan vendor:publish --tag="filament-spatie-media-library-plugin-views"
   

3. Event Listeners Listen for media events to trigger custom logic:

   use Spatie\MediaLibrary\Events\MediaWasAdded;
   
   MediaWasAdded::listen(function (MediaWasAdded $event) {
       // Send notification or log the upload
   });
   

4. API Integration Expose media endpoints via Filament’s API resources:

   use Filament\Resources\Resource;
   use Filament\Resources\Tables;
   use Filament\Tables;
   
   class MediaLibraryResource extends Resource
   {
       public static function table(Table $table): Table
       {
           return $table->columns([
               // ...
           ]);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Collection Mismatches

   • Ensure the collection attribute in Filament fields matches the collections registered in your model. Mismatches will result in silent failures or empty uploads.
   • Fix: Double-check registerMediaCollections() and field configurations.

2. Disk Permissions

   • If using local storage, ensure the storage/app/public directory is writable.
   • For cloud storage (e.g., S3), verify credentials and bucket permissions.
   • Fix: Run php artisan storage:link and check .env for correct disk settings.

3. Large File Uploads

   • Default Laravel limits (e.g., upload_max_filesize in php.ini) may block large uploads.
   • Fix: Increase limits in php.ini or use chunked uploads with libraries like spatie/laravel-uploads.

4. Caching Issues

   • Media thumbnails or metadata may not update immediately due to caching.
   • Fix: Clear Filament cache (php artisan filament:cache:clear) or use Media::refreshCache().

5. Concurrent Uploads

   • Rapid consecutive uploads can cause race conditions or duplicate filenames.
   • Fix: Use unique filenames or UUIDs in your registerMediaConversions().

Debugging

1. Log Media Events Enable Spatie’s logging to debug media operations:

   'logging' => [
       'enabled' => true,
       'channel' => 'single',
   ],
   

   in config/medialibrary.php.

2. Check Disk Contents Verify files are being saved to the correct disk:

   php artisan storage:disk --list
   php artisan storage:link
   

3. Filament Plugin Debugging Enable debug mode for the plugin:

   SpatieMediaLibraryPlugin::make()->debug(true),
   

   in your AdminPanelProvider.

4. Database Integrity Ensure the media table exists and has the correct structure:

   php artisan migrate
   

Config Quirks

1. Default Collection The plugin assumes a default collection if none is specified. Override in config:

   'default_collection' => 'default',
   

2. Directory Structure Custom directories (e.g., directory('thumbnails')) are relative to the collection’s root. Ensure paths are correct:

   storage/app/public/images/thumbnails/
   

3. Mime Type Restrictions The plugin enforces MIME type validation. Extend allowed types in config:

   'allowed_mime_types' => [
       'images' => ['image/jpeg', 'image/png', 'image/webp'],
       'documents' => ['application/pdf', 'application/msword'],
   ],
   

Extension Points

1. Custom Media Models Extend the default Spatie\MediaLibrary\Models\Media model:

   class CustomMedia extends \Spatie\MediaLibrary\Models\Media
   {
       protected $casts = [
           'custom_field' => 'boolean',
       ];
   }
   

   Update the plugin’s config to use your model:

   'model' => \App\Models\CustomMedia::class,
   

2. Custom Fields Create reusable media fields by extending SpatieMediaLibraryFileUpload:

   class CustomMediaUpload extends SpatieMediaLibraryFileUpload
   {
       protected string $view = 'filament.spatie-media-library-plugin.custom-field';
   
       public function configure(): static
       {
           return $this->image()->required();
       }
   }
   

3. Custom Actions Add actions to the media manager panel:

   use Filament\Tables\Actions\Action;
   
   SpatieMediaLibraryPlugin::make()->registerTableActions([
       Action::make('customAction')
           ->action(function (Media $record) {