Spatie Media Library driver

The SpatieMediaLibraryDriver lets you browse and manage your existing Spatie Media Library records directly inside the Media Library UI – organised into virtual folders by collection, model type, and individual model.

Installation

composer require spatie/laravel-medialibrary

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

use RalphJSmit\Filament\MediaLibrary\Drivers\SpatieMediaLibraryDriver;

$plugin
    ->driver(SpatieMediaLibraryDriver::class)

use RalphJSmit\Filament\MediaLibrary\Drivers\SpatieMediaLibraryDriver\SpatieMediaGroupable;

$driver->spatieMediaLibraryGroupables([
    SpatieMediaGroupable::Collection,
    SpatieMediaGroupable::ModelType,
    SpatieMediaGroupable::Model,
])

By default the driver surfaces all media records from your database. Use the scoping methods below to limit which records are visible.

Restricting by model type

Pass an array of fully-qualified model class names to ->modelTypes(). Only media belonging to those models will appear:

use App\Models\Post;
use App\Models\Page;

$driver->modelTypes([Post::class, Page::class])

The driver resolves morph map aliases automatically, so you don't need to pass the alias string – the class name is always correct.

Restricting by collection

Pass an array of collection name strings to ->collections(). Only media in those collections will appear:

$driver->collections(['images', 'documents'])

Combining both

You can combine ->modelTypes() and ->collections() freely. Both constraints are applied at the database query level, so only media matching both criteria is loaded:

use App\Models\Post;

$driver
    ->modelTypes([Post::class])
    ->collections(['images', 'thumbnails'])

The driver derives folder and file-info labels automatically, but you can override every label to match your application's language and branding.

Model instance labels

By default the driver uses the model's name attribute, or falls back to #<id> when no name column exists. Override this per-model by calling ->getModelLabelUsing() with a closure that receives the model instance and returns a string (or null to fall through to the next registered callback):

use App\Models\Post;

$driver->getModelLabelUsing(function ($model): ?string {
    if ($model instanceof Post) {
        return $model->title;
    }

    return null;
})

You may call ->getModelLabelUsing() multiple times. The driver tries each callback in order and uses the first non-null value.

Model type labels

The folder label for a ModelType groupable defaults to the plural Filament model label (e.g. "Posts"). Override it with ->getModelTypeLabelUsing(), which receives the fully-qualified class name:

use App\Models\Post;

$driver->getModelTypeLabelUsing(function (string $modelClass): ?string {
    if ($modelClass === Post::class) {
        return 'Blog posts';
    }

    return null;
})

Collection labels

Collection names default to Str::ucfirst($collectionName) (e.g. "featured_images" → "Featured_images"). You have three ways to customise them, in increasing order of specificity:

For all collections at once, use ->getCollectionLabelUsing():

$driver->getCollectionLabelUsing(function (string $collection): string {
    return str($collection)->replace('_', ' ')->title()->toString();
})

For a single collection, use ->collectionLabel():

$driver->collectionLabel('featured_images', 'Featured images')

For several collections at once, use ->collectionLabels():

$driver->collectionLabels([
    'featured_images' => 'Featured images',
    'og_images'       => 'OG images',
])

When both ->collectionLabels() and ->getCollectionLabelUsing() are configured, the per-collection label takes priority; the callback is only called when no explicit label is found.

Making the model name clickable

In the file info panel, the driver shows which model the media is attached to. By default this is plain text. Call ->getModelUrlUsing() to turn it into a link – useful for jumping straight to the Filament resource edit page:

use App\Models\Post;
use App\Filament\Resources\PostResource;

$driver->getModelUrlUsing(function ($model): ?string {
    if ($model instanceof Post) {
        return PostResource::getUrl('edit', ['record' => $model]);
    }

    return null;
})

Return null for models where you don't want a link. Like ->getModelLabelUsing(), you can call ->getModelUrlUsing() multiple times and the first non-null result wins.

The SpatieMediaLibraryDriver is designed around the structure Spatie Media Library imposes. That structure comes with a few constraints worth understanding before you commit to this driver.

No folder creation or moving

Virtual folders are derived entirely from media record attributes – they are not stored anywhere. Because of that, the driver cannot create new folders, rename virtual folders, or move files between folders. Attempting to do so throws a RuntimeException. The related UI actions (create folder, move) are automatically hidden.

Uploading a file is only possible when the current folder resolves to a specific model instance (a Model groupable). The upload is then attached to that model under the resolved collection name.

Media records are not re-usable

Each Spatie media record can only be attached to one model at a time. If you need to link the same file to multiple models, this driver is not the right fit.

The Media Library Item-driver solves this by placing an intermediate MediaLibraryItem model between your models and the Spatie media records, making files fully re-usable across your application.

That's it! You now have a fully functional Media Library that surfaces your existing Spatie Media Library records – organised into virtual folders by collection, model type, and model – with no changes required to your existing data.

If you need re-usable media items that can be linked to multiple models, take a look at the Media Library Item-driver instead.