Filament Plugins

Purchase

Guides

Installation Upgrade guide (beta) Principles Drivers Theming

Drivers

Media Library Item-driver Storage/disk driver Spatie Media Library driver Custom driver

Components

Media Picker Media Column Media Entry

Media Library

Scoped folder File types Navigation Bulk actions Filters Sorters

Advanced

Configurable schemas Modifications Programmatic upload

Integrations

Filament Upload Pro

Upgrade guide (beta)

If you are upgrading from V3 to V4 of the Filament Media Library, please read this guide carefully as there are some breaking changes.

Please note that the V4 version is currently in beta to seek feedback. This means that some features might not be fully implemented yet or might evolve.

Upgrade Steps

1

Upgrade Composer version

To upgrade to Filament Media Library Pro V4, you need to update your Composer dependency. Run the following command in your terminal:

terminal 

composer require ralphjsmit/laravel-filament-media-library:"^4.0-beta4" spatie/laravel-medialibrary:^11.0

Or update your composer.json by increasing the version to ^4.0:

composer.json 

{
    "require": {
        "ralphjsmit/laravel-filament-media-library": "^4.0-beta4",
        "spatie/laravel-medialibrary": "^11.0"
    }
}

Also make sure to explicitly require the spatie/laravel-medialibrary dependency. As the Media Library V4 supports multiple drivers, the dependency is not included anymore by default and must be required manually.

2

Review custom theme

Please verify that you are using a custom theme compatible with Filament V4.

Next, open up the theme.css file for the custom theme and add the following lines:

resources/css/filament/{your-panel}/theme.css 

@import '../../../../vendor/ralphjsmit/laravel-filament-media-library/resources/css/index.css';

Remove any @source imports as these are handled automatically by the plugin.

You should also add this line to any CSS files that you are using if you are planning to use the Media Library outside a Filament panel. You might need to correct the number of ../ to reach the vendor directory depending on where your CSS file is located.

3

Review `$plugin` methods

Next, for each panel, you need to review the methods that you are calling on the $plugin = FilamentMediaLibrary::make() object:

app/Providers/Filament/YourPanelProvider.php 

use RalphJSmit\Filament\MediaLibrary\FilamentMediaLibrary;

FilamentMediaLibrary::make()
    ->diskVisibilityPrivate()   // Automatically detected disk visibility now
    ->diskVisibility('private') // Automatically detected disk visibility now
    ->diskVisibilityPublic()    // Automatically detected disk visibility now
    ->diskVisibility('public')  // Automatically detected disk visibility now
    // Optional, to stay in line with Filament best practices:
    ->navigationIcon('heroicon-o-video-camera') 
    ->activeNavigationIcon('heroicon-s-video-camera') 
    ->navigationIcon(Heroicon::OutlinedVideoCamera) 
    ->activeNavigationIcon(Heroicon::VideoCamera) 
    ->modelItem(\App\Models\MediaLibraryItem::class) 
    ->modelFolder(\App\Models\MediaLibraryItem::class)                                                                                                                                                             
    ->driver(modifyDriverUsing: function (MediaLibraryItemDriver $driver) { 
        $driver 
            ->mediaLibraryItemModel(\App\Models\MediaLibraryItem::class) 
            ->mediaLibraryFolderModel(\App\Models\MediaLibraryFolder::class); 
    }) 
   ->firstAvailableUrlConversions(...)

Next, you should also review the Media-conversions that are generated by the package. As the package now comes with an integration with Glide, which can generate images in the ideal size very effectively on-the-fly with less compute, the package does not enable any Spatie MediaLibrary conversions by default.

If you are upgrading, you will likely want to keep the conversions enabled, which you can do by opting in to conversions on $driver->conversions():

php 

$plugin
    // Copy the below method configuration (if any)...
    ->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)
    ->driver(modifyDriverUsing: function (MediaLibraryItemDriver $driver) {
        $driver
            ->conversions() 
            // And move them into the `$driver` instead...
            ->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); 
    })
    // The following methods can also be removed:
    ->thumbnailMediaConversion('thumb') 
    ->mediaPickerMediaConversion('thumb')
4

Review `MediaPicker`

Next, review the instances of the MediaPicker in your forms:

php 

 use RalphJSmit\Filament\MediaLibrary\Forms\Components\MediaPicker; 
 use RalphJSmit\Filament\MediaLibrary\Filament\Forms\Components\MediaPicker; 

MediaPicker::make('images')
  ->buttonLabel('Select brochure') 
  ->openModalActionColor('success') 
  ->selectMediaActionLabel('Select brochure') 
  ->selectMediaActionColor('success') 
  // Filename is now shown by default so option can be removed:
  ->showFileName()
5

Review `MediaColumn`

Review the instances of the MediaColumn in your tables. If you are using the MediaColumn to display media from a relationship, you now need to explicitly add the ->relationship() method:

php 

 use RalphJSmit\Filament\MediaLibrary\Tables\Columns\MediaColumn; 
 use RalphJSmit\Filament\MediaLibrary\Filament\Tables\Columns\MediaColumn; 

MediaColumn::make('images')
  ->relationship()
6

Review `MediaEntry`

Review the instances of the MediaEntry in your infolists. As using a relationship is not explicitly required anymore, you now need to explicitly add the ->relationship() method:

php 

 use RalphJSmit\Filament\MediaLibrary\Infolists\Components\MediaEntry; 
 use RalphJSmit\Filament\MediaLibrary\Filament\Infolists\Components\MediaEntry; 

MediaEntry::make('featuredImage')
  ->relationship()

Alternatively, you can also use it without a relationship:

php 

 MediaEntry::make('featuredImage') 
 MediaEntry::make('featured_image_id') 

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

Review `spatie/laravel-media-library` config

This step is only if you were using a private disk for your Media Library. In that case, open the config/media-library.php and remove the custom url_generator line:

config/media-library.php 

/*
* When urls to files get generated, this class will be called. Use the default
* if your files are stored locally above the site root or on s3.
*/
 'url_generator' => RalphJSmit\Filament\MediaLibrary\UrlGenerator\MediaLibraryUrlGenerator::class,
 'url_generator' => Spatie\MediaLibrary\Support\UrlGenerator\DefaultUrlGenerator::class,
8

Remove `@mediaPickerModal`

This step is only for those who were using the Media Library in forms outside of any panel and who had the @mediaPickerModal directive in their Blade view.

In V4, the modal will now use Filament Actions, so you can remove the Blade-directive. Make sure though that you do have the default Filament Actions modals component somewhere in your layout instead:

resources/components/layouts/app.blade.php 

 @mediaPickerModal 
 <x-filament-actions::modals />
9

Rename Model imports

If you are importing the MediaLibraryItem or MediaLibraryFolder models in your code, you need to update the namespace:

php 

use RalphJSmit\Filament\MediaLibrary\Media\Models\MediaLibraryItem;
use RalphJSmit\Filament\MediaLibrary\Media\Models\MediaLibraryFolder;

use RalphJSmit\Filament\MediaLibrary\Models\MediaLibraryItem;
use RalphJSmit\Filament\MediaLibrary\Models\MediaLibraryFolder;
10

Review programmatic upload

This step only applies to those who are programmatically adding files to the Media Library.

Rather than calling MediaLibraryItem::addUpload(...), you will now need to instantiate the driver:

php 

use Illuminate\Http\UploadedFile;
use RalphJSmit\Filament\MediaLibrary\Models\MediaLibraryItem;
use Filament\Facades\Filament;
use RalphJSmit\Filament\MediaLibrary\FilamentMediaLibrary;
use RalphJSmit\Filament\Explore\Data\TemporaryFileUploadData;
 
$uploadedFile = /** */;
 
$mediaItem = MediaLibraryItem::addUpload($uploadedFile);

$driver = Filament::getPanel('admin')
    ->getPlugin(FilamentMediaLibrary::make()->getId())
    ->getDriver();

$fileData = $driver->createFile(
    folder: null, 
    temporaryFileUploadData: TemporaryFileUploadData::fromUploadedFile($uploadedFile)
);

If you'd like to provide a folder to upload in:

php 

$mediaLibraryFolder = MediaLibraryFolder::find(1); // However you get the folder...

$fileData = $driver->createFile(
    folder: FileData::fromMediaLibraryFolder($mediaLibraryFolder), 
    temporaryFileUploadData: TemporaryFileUploadData::fromUploadedFile($uploadedFile)
);

To upload a file to the Media Library from a disk, use the fromDisk() method:

php 

$fileData = $driver->createFile(
    folder: null, 
    temporaryFileUploadData: TemporaryFileUploadData::fromDisk(
        disk: 's3', 
        path: 'path/to/file.jpg', 
        shouldPreserveOriginalFile: true // Default false, can be set to true if you want to keep the original file on the disk
    ),
);

If you would need to upload images from other sources, please let me know and I can provide alternative methods on the TemporaryFileUploadData object.

11

Review V2 config

This step is only for those who are already using the plugin since version 2 and who have the config/filament-media-library.php published.

If you have this file, then remove the file and implement any configurations on the $plugin object instead. In V3 the plugin also no longer used the configuration file, but any values were mapped to the $plugin object. In V4, the plugin has been entirely re-built and no longer supports the V2 configuration file.

This file was not included in V3 of the Media Library, but it was still read for backwards compatibility reasons.

12

Review `spatie/laravel-tags` usage

This step is only for those who integrated the V3 with spatie/laravel-tags using the example code-snippets.

In V4, the Media Library has built-in support for spatie/laravel-tags and you can now enable it using the ->spatieTagsIntegration() method on the $plugin object:

app/Providers/Filament/YourPanelServiceProvider.php 

$plugin
    ->spatieTagsIntegration()
    // Remove if the only use case was adding the `HasTags` trait:
    ->modelItem(\App\Models\MediaLibraryItem::class)

app/Providers/AppPanelProvider.php (or other file) 

MediaLibrary::registerMediaInfoFormFields(fn (array $schema): array => [
    ...$schema,
    SpatieTagsInput::make('tags'),
]);

app/Models/MediaLibraryItem.php 

class MediaLibraryItem extends \RalphJSmit\Filament\MediaLibrary\Media\Models\MediaLibraryItem
{ 
    use HasTags;
}

The required Spatie\Tags\HasTags trait is now automatically loaded into the MediaLibraryItem model, so you no longer need to add it yourself. If you were extending the MediaLibraryItem model just to add the HasTags trait, you can now entirely remove the extended model and the $plugin->modelItem() call as the trait is now inserted automatically if you have spatie/laravel-tags installed.

13

Review custom pages

This step is only for those who created custom pages by extending the UploadMedia, BrowseLibrary and MediaInfo classes.

app/Providers/Filament/YourPanelServiceProvider.php 

$plugin
    ->uploadMediaComponent(\App\Livewire\MediaLibrary\UploadMediaComponent::class)  
    ->browseLibraryComponent(\App\Livewire\MediaLibrary\BrowseLibraryComponent::class)  
    ->mediaInfoComponent(\App\Livewire\MediaLibrary\MediaInfoComponent::class)

The Media Library V4 has been re-built from the ground up using Filament Schemas. The above components do therefore no longer exist and the methods have been removed.

If you were adding custom functionality to components, please review the current documentation and features of the V4 version, as many features that previously required custom code are now natively supported.

Furthermore, if you have any further customizations, reach out to support@ralphjsmit.com to get help on how to best implement these in the new version.

14

Review `MediaLibrary` facade

This step only applies to who are using the RalphJSmit\Filament\MediaLibrary\Facades\MediaLibrary facade in their code.

Custom conversions can now be registered using the registerConversions() method on the driver instead:

app/Providers/ExampleServiceProvider.php 

 MediaLibrary::registerMediaConversions(function (MediaLibraryItem $mediaLibraryItem) { 
    $mediaLibraryItem->addMediaConversion('custom')->width(368)->height(232)->sharpen(10); 
 });

app/Providers/Filament/YourPanelProvider.php 

$plugin
    ->driver(modifyDriverUsing: function (MediaLibraryItemDriver $driver) {
        $driver
            ->registerConversions(function (MediaLibraryItem $mediaLibraryItem) { 
                $mediaLibraryItem->addMediaConversion('custom')->width(368)->height(232)->sharpen(10); 
            }) 
    })

During the beta, comment out the use of the MediaLibrary facade for the remaining methods. Alternative methods will be provided during the beta period. Please reach out if this is crucial for you.

The foundation of the Media Library has been several years old. The focus of this upgrade has been on rebuilding the Media Library from the ground up, lifting it to fully adhere to modern Filament V4 coding standards and best practices. Shortly, making it ready for the next 5 years.

Furthermore, the Media Library is now running on a driver-based system, so projects don't have to use the MediaLibraryItem-based structure anymore, but can also easily run the Media Library on a (pre-existing) storage/disk, or plugging in their current Spatie Media Library-library, without requiring MediaLibraryItem. Furthermore, one can also provide custom drivers, ensuring that virtually any library can run and that legacy projects can always also easily be converted to the Media Library by just implementing a custom driver.

Finally, the Media Library has been built from the ground up using Filament Schemas and Filament Actions. This allows extreme levels of customization and flexibility.

I hope you enjoy using the new Media Library as much as I enjoyed building it! If you have any questions or feature requests, please send an e-mail to support@ralphjsmit.com.

© FilamentPlugins.com ✦ 2022 – 2025 ✦ All rights reserved.