Drivers

The default driver is the so-called MediaLibraryItemDriver. This driver is the one that has historically powered the Media Library. The driver is a combination of spatie/laravel-media-library and two custom database models: MediaLibraryItem and MediaLibraryFolder.

The benefit of this driver is that is combines both the advantages of Spatie Media Library, and it makes media items re-usable. The issue with Spatie Media Library is that each media record can only be linked to one other record. By placing an intermediate MediaLibraryItem model between your models and the Spatie media records, the Spatie media item is now suddenly reusable.

Using this driver in your forms looks something like:

MediaPicker::make('featured_image_id')
    ->label('Featured image')
    ->required(),

Then, this will store the id of the MediaLibraryItem in the featured_image_id field of your model. Then you can even access this image in an intuitive way using a relationship:

class YourModel extends Model
{
    public function featuredImage(): BelongsTo
    {
        return $this->belongsTo(MediaLibraryItem::class, 'featured_image_id');
    }
}

Resulting in the following clean code:

<img 
    src="{{ $yourModel->featuredImage->getUrl('thumb') }}" 
    alt="{{ $yourModel->featuredImage->name }}"
>

This driver is the recommended choice when installing the Media Library. As it is database-driven, it is also great for storing additional data on your media items, such as alt-text, copyright-information, photographer, by just adding a column to your filament_media_library table. Additionally, you can then easily build custom filters and custom sorters based on these.

It is also possible to write an importer to migrate existing files to this driver. Contact me with some details about your current structure to get a free personalised example script.

The second provided driver is the so-called FilesystemStorageDriver. This driver is a more straightforward driver that simply stores files on a filesystem disk of your choice. This driver is a great choice when you already have a disk with existing files, and now need a nice way to manage them in Filament.

It is also possible to provide authorization logic to this driver, making sure that no files are deleted from the Media Library that are used on your models.

Using this driver in your forms looks something like:

MediaPicker::make('featured_image_path')
    ->label('Featured image')
    ->required(),

This will store the path of the selected file on the featured_image_path field of your model. Then, you are free to access the image in any way you want.

Finally, if you have an existing library of files managed by Spatie Media Library, and each linked to one model, you can also use the SpatieMediaLibraryDriver. This driver will allow to still provide your users with a library to manage files, with the exception that it is generally not possible to upload new files through the Media Library, but only inside your forms through the MediaPicker.

The downside of this library is that you cannot re-use files, as each Spatie media record can only be linked to one model. If you need re-usable files, consider switching to the MediaLibraryItemDriver instead.

MediaPicker::make('featured_image')
    ->label('Featured image')
    ->required(),

This will display any media files that are linked to your model, and allow you to upload new ones.