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.

Pros

• Image/PDF conversions built-in.
• Proven technology & scalability with over 28 million installs.
• Can handle non-unique file names easily.
• Easy response-image integration for use on (Blade-based) frontends.
• Link selected images to your models using a database ID and foreign key.
• More performant searching through large libraries.

Cons

• Storing a selection of multiple MediaLibraryItem's can be done using a JSON-column with integer IDs or a separate pivot table, which is less intuitive.

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.

By default, all images in the Media Library are displayed using Glide (if you have the gd or imageick extension enabled). This is very convenient, as Glide can generate all images from the Media Library into a perfect size on-the-fly, without the need to create and store multiple versions of the same image. However, in some cases you might want to create and store multiple versions of the same image, for example when you need to perform more complex image manipulations or prefer to store it, you can use Spatie Medialibrary's conversions for that.

Enabling conversions

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

$driver->conversions()

Working with media conversions

By default, the plugin registers four media conversions. The media conversions are:

1. responsive
2. small (known as 400)
3. medium (known as 800)
4. thumb

Media conversions not being generated

In case your media conversions are not being generated (or only the thumb conversion), please ensure you have correctly set up a queue. The thumb conversion will be generated directly when the user uploads an image (to always have one conversion available), whereas the other conversions will be generated in the background on the queue in order to not unnecessarily slow down the upload so much. See also here.

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)

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.