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

Filament Media Library

A powerful media library package for Filament with MediaPicker form component, drag & drop uploads, and full integration with FileManager.

Requirements

Features

• Media Library Page - Full standalone file manager in navigation
• MediaPicker Form Component - Select files from library or upload new ones
• Two Modes - Browse-only (default) or Upload mode
• Browse Library Modal - Full file browser with folder navigation
• Single & Multiple Selection - Support for cover images and galleries
• Gallery Grid Layout - Unified container with customizable columns and height
• Interactive Media Players - Built-in video and audio players in grid mode
• Auto Directory Structure - Automatically creates folder hierarchy based on resource name
• Multi-tenancy Support - Full tenant isolation out of the box
• Filament Plugin - Easy registration with customizable navigation

Installation

Quick Install (Recommended)

Run the install command to automatically configure everything:

This will:

• Publish the config file
• Run migrations
• Configure storage (DO Spaces/S3 if selected)
• Configure your Filament theme CSS for Tailwind

Then rebuild your theme:

Manual Installation

1. Register Plugin

Add the plugin to your Filament panel in AdminPanelProvider.php:

This automatically adds the Media Library page to your navigation.

2. Publish Config (Optional)

3. Run Migrations

4. Publish Assets

The package includes its own CSS for hover effects and animations. Publish the assets:

Note: This step is required after installation or updating the package. The CSS is automatically registered with Filament's asset system.

5. Configure Custom Theme (Optional - for Media Library Page)

If you're using the Media Library page (not just MediaPicker), add the package views to your Filament theme CSS (resources/css/filament/admin/theme.css):

Then rebuild your theme:

Plugin Options

Customize the Media Library page:

Disable the page (use only MediaPicker component):

Configuration

Config file: config/filament-media-library.php

Key Settings

Cloud Storage (S3 / DigitalOcean Spaces)

The package fully supports S3-compatible cloud storage including AWS S3 and DigitalOcean Spaces.

1. Configure Filesystem Disk

Add to config/filesystems.php:

2. Environment Variables

For DigitalOcean Spaces:

For AWS S3:

3. Set Media Library Disk

Update your .env:

Features

• Automatic thumbnail generation - Works seamlessly with cloud storage
• Public URLs - Files are publicly accessible via CDN
• Visibility control - Set 'public' or 'private' visibility per file
• Temporary URLs - Private files use signed temporary URLs (S3 feature)

Usage

Basic Usage (Browse Mode - Default)

By default, MediaPicker shows a "Browse Library" button to select from existing files:

Upload Mode

Enable drag & drop upload with allowUpload():

Model Setup

Minimum required:

Migration:

Auto Directory Structure

Automatically organize uploads into folders based on resource:

Available placeholders:

Example folder structure:

Component Options

File Type Filters

Selection Mode

Modal Customization

Upload Settings

Visibility & State

Gallery Layout (Grid Mode)

Display multiple files in a customizable grid layout:

Grid Mode Features:

• Unified container with files and "Add" button together
• Drag & drop directly onto the grid area with prominent overlay
• Interactive video player with play/pause
• Interactive audio player with purple gradient background
• Hover effects on cards with ring highlight
• Remove button appears on hover (red on hover)
• Smooth animations and transitions

Interactive Media Players

In grid mode, media files have built-in players:

Video:

• Click play button to start video
• Native controls appear (play, pause, progress, volume, fullscreen)
• Thumbnail shown when paused

Audio:

• Purple gradient background
• Click to play/pause
• Shows filename

How It Works

Two Modes

1. Browse Mode (default) - Click "Browse Library" button

   • Opens modal with full file browser
   • Navigate folders, search files
   • Select existing files from library
2. Upload Mode - Enable with ->allowUpload()
   • Shows drag & drop zone
   • Files upload immediately
   • Stored in configured directory
   • ID saved to form field

Data Storage

Single file: Stores integer ID

Multiple files: Stores JSON array of IDs

Optional: Helper Methods

Add these to your model for convenient access:

API Usage (Frontend)

Get file data for API responses:

Multi-tenancy

The package automatically handles tenant isolation:

1. All files are scoped to current tenant
2. Folder structure is tenant-specific
3. Users can only see their tenant's files

Tenant is resolved from (in order):

1. Container-bound tenant
2. Filament Filament::getTenant()
3. Authenticated user's tenant_id
4. Session filament_tenant_id

Synchronization with FileManager

This package uses the same database tables as FileManager:

• file_folders - Folder structure
• file_items - File records
• file_tags - File tags
• file_versions - File versions
• file_shares - Shared links

Files uploaded via MediaPicker appear in FileManager and vice versa.

Artisan Commands

Install Command

Migrate Storage Command

Migrate files between storage disks (e.g., local to cloud):

Thumbnails

The package generates two layers of thumbnails out of the box:

1. Admin preview — a single 300×300 thumbnail stored in the thumbnail_path column on media_items and used in the Filament admin grid. Generated synchronously on upload.

2. Responsive thumbnails — a configurable set of widths stored under {thumbs_path}/{media_id}/{size}/{filename}.{format}. Generated asynchronously by GenerateThumbnailsJob, intended for the front-end. Driver is selected automatically (Imagick → GD → noop).

Configuration

API on MediaItem

getThumbnailUrl() (legacy admin preview) and the thumbnail_path column continue to work as before.

Driver Selection

Sizes larger than the source width are skipped automatically. SVG and non-image items are also skipped.

Regenerating Thumbnails

Migration from Custom Observer

If your application previously implemented its own ThumbnailGenerator + MediaItemObserver to produce responsive thumbs, you can drop them after upgrading to v1.3 — the package now handles this end to end. Update consumer code that reads paths to use $item->thumbUrl($size) instead of building paths by hand.

Updating the Package

After updating via composer, run:

UI/UX Features

Drag & Drop Upload

When allowUpload() is enabled:

• Clear "Drop to upload" overlay when dragging files
• Backdrop blur effect for better visibility
• Prominent border highlight

Card Hover Effects

• Ring highlight on card hover
• Remove button hidden by default, appears on hover
• Remove button turns red when hovered
• Subtle overlay on image cards

Upload Progress

• Animated progress bar with glow effect
• Shimmer animation during upload
• Success checkmark with green glow
• Error state with retry button

Responsive Design

All components are fully responsive and work on mobile devices.

Troubleshooting

Upload returns 500 error

Check Laravel log for details:

Common issues:

• tenant_id NULL - User not authenticated or tenant not resolved
• Permission denied - Check storage folder permissions
• File too large - Increase upload_max_filesize in php.ini

Files not showing

1. Clear cache: php artisan cache:clear
2. Check tenant scope is correct
3. Verify files exist in database

Modal not opening

1. Check browser console for JS errors
2. Ensure Alpine.js is loaded
3. Clear Filament cache: php artisan filament:cache-components

License

MIT License - see LICENSE file for details.