Media Library Item-driver

The MediaLibraryItemDriver allows you to combine the best of Spatie Media Library with the flexibility of re-using media items across models. Furthermore, storing media items is as easy as storing just a single ID.

Installation

php artisan vendor:publish --tag="filament-media-library-migrations"

composer require spatie/laravel-medialibrary

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

MEDIA_DISK=s3

That's it! You now have a fully functional Media Library running Spatie Medialibrary as a driver.

Conversions

As the Media Library Item Driver is built on top of Spatie Medialibrary, it fully supports all of Spatie Medialibrary's features, including image conversions.

Enabling conversions

Conversions are opt-in. To enable support, call the driver ->conversions() method:

$driver->conversions()

Working with media conversions

By default, the plugin registers four media conversions:

By default, the thumb conversion runs synchronously on upload so a preview is always immediately available; the other conversions are queued.

Modifying media conversions

You can modify these conversions using the following methods:

use Spatie\MediaLibrary\Conversions\Conversion;

$driver
    ->conversionResponsive(enabled: true, modifyUsing: function (Conversion $conversion)  {
        // Apply any modifications you want to the conversion, or omit to use defaults...
        return $conversion->keepOriginalImageFormat();
    })
    ->conversionMedium(enabled: true, width: 800)
    ->conversionSmall(enabled: true, width: 400)
    ->conversionThumb(enabled: true, width: 600, height: 600)

Modifying every conversion at once

If you want to apply the same modification to every built-in conversion (responsive, small, medium, thumb), you can use ->modifyConversionsUsing(). The callback receives each conversion in turn and is applied on top of the per-conversion modifyUsing: callbacks:

use Spatie\MediaLibrary\Conversions\Conversion;

$driver
    ->modifyConversionsUsing(function (Conversion $conversion) {
        $conversion->keepOriginalImageFormat();
    });

This is convenient when you have a setting that applies across the board – like keeping the original image format, queueing all conversions on the same queue, or applying a watermark.

Customizing the Spatie media collection

By default, every MediaLibraryItem registers a Spatie media collection named media. If you need to customize that collection per item – for example to apply single file collection behaviour or to register accept-callbacks – use ->mediaCollection():

use Spatie\MediaLibrary\MediaCollections\MediaCollection;

$driver
    ->mediaCollection(function (MediaCollection $mediaCollection) {
        $mediaCollection->singleFile();
    });

The callback receives the Spatie MediaCollection instance and is invoked when registering the collection on the MediaLibraryItem.

Registering custom media conversions

If you want to register additional media conversions, you can do so using the ->registerConversions() method:

$driver
    ->registerConversions(function (MediaLibraryItem $mediaLibraryItem, Media $media = null) {
        $mediaLibraryItem
            ->addMediaConversion('test');
    
        // ..
    })

You are free to register as many conversions as you like. However, be aware that each new conversion takes up more disk space.

Custom models

If you want to use custom Eloquent models for the Media Library item or folder, configure them on the MediaLibraryItemDriver inside your modifyDriverUsing callback:

use RalphJSmit\Filament\MediaLibrary\Drivers\MediaLibraryItemDriver;

$driver
    ->mediaLibraryItemModel(\App\Models\MediaLibraryItem::class)
    ->mediaLibraryFolderModel(\App\Models\MediaLibraryFolder::class);