Download the PHP package crumbls/filament-media-library without Composer

Filament Media Library

A WordPress-style media library for Filament 5. Provides a central media pool with polymorphic attachments, so any model in your application can reference shared media through a clean pivot table.

Built on top of Spatie Media Library for file handling and image conversions.

Requirements

• PHP 8.2+
• Laravel 12+
• Filament 5+
• Spatie Laravel Media Library 11+

Installation

The package auto-discovers its service provider. Migrations run automatically -- no publishing required.

Run the migrations:

Register the plugin in your Filament panel provider:

Configuration

Publish the config file to customize settings:

Usage

Media Library Page

Once the plugin is registered, a "Media Library" page appears in your Filament panel navigation. It provides:

• Grid view of all uploaded media with thumbnails
• Drag-and-drop file uploads
• Search across title, alt text, caption, and description
• Type filtering (images, videos, documents)
• Detail modal with editable metadata (title, alt text, caption, description)
• Inline image editing (crop, rotate, flip) via CropperJS
• File URL display for easy copying

Attaching Media to Models

Add the HasMediaLibrary trait to any Eloquent model:

This gives you a full API for managing media attachments:

MediaPicker Form Component

Use the MediaPicker in any Filament form to let users select media from the library:

Multiple selection:

Limit selections:

Named collection:

The picker opens a modal with search, pagination, and thumbnail previews. Selected media is stored as an ID (single) or array of IDs (multiple) on the model.

Database Column Requirements

The MediaPicker stores a media_library.id reference directly on your model's table. You must ensure:

1. The column exists -- Add a nullable unsigned big integer column for the field name you pass to MediaPicker::make().
2. The column is fillable -- Add the column name to your model's $fillable array.

Example migration for adding an avatar column to a users table:

Then in your model:

If you have an accessor on the same column (e.g., getAvatarAttribute()), remove it -- the MediaPicker needs the raw integer ID during form hydration. Use a separate method to resolve the media URL:

MediaColumn Table Column

Display media thumbnails in Filament tables:

Options:

Performance tip: Eager-load the media relation to avoid N+1 queries:

Media Model

The Media model wraps Spatie Media Library and provides convenient accessors:

Metadata fields:

The model uses soft deletes. Each record gets an auto-generated UUID and tracks uploaded_by (foreign key to users).

Database Schema

The package creates two tables:

media_library -- Central media records

mediables -- Polymorphic pivot table

Spatie Media Library also creates its own media table for the underlying file records.

Publishing Assets

Storage Disk

Set the storage disk via environment variable or config:

Any disk defined in config/filesystems.php works -- public, s3, r2, or a custom disk.

Extending the Media Model

Swap in your own Media model by updating the config:

Your custom model should extend the package's Media model:

Security

Uploads are validated server-side:

• MIME type validation -- Files are checked against accepted_file_types using glob-style matching (e.g., image/* matches image/png). Rejected files are not stored.
• File size limits -- Enforced against max_file_size config value.
• Filename sanitization -- Uploaded filenames are slugified to strip path traversal sequences, special characters, and double extensions.
• Metadata validation -- Title and alt text are limited to 255 characters, caption to 1000, description to 5000.

Rejected uploads dispatch an fml-uploads-rejected Livewire event with details for frontend notification.

Development

Code Style

This project uses Laravel Pint for code formatting. A pre-push git hook runs Pint automatically and blocks pushes with style violations.

Run Pint manually:

Static Analysis

Larastan is configured at level 5:

Roadmap

Add throttling to uploads. Add lifecycle events. Add tenant scoping.

Testing

The package uses Pest with 197 tests:

License

MIT. See LICENSE.