Filament Media — Media Manager for Filament

A full-featured Media Manager plugin for Filament v4 and v5. Upload, organise, tag, version, and serve media files across local and cloud storage — with a modern UI, fine-grained access control, and a developer-friendly service architecture. The foundation that codenzia/filament-dam builds its enterprise DAM features on top of.

Try it live: A working integration is included in the Codenzia plugins demo at /admin/demo/media.

Features

File Management — Drag-and-drop uploads with progress tracking, chunked uploads for large files, upload from URL (with SSRF protection), multi-file selection, batch operations, copy/move/rename, alt text, automatic thumbnails with optional watermarks.

Folders — Nested folder structure with unlimited depth, color-coded folders, drag-and-drop organization, automatic folder resolution from file paths.

Tags & Collections — Tag files and folders, organize into named collections, filter and search by tags, bulk tagging, popular tags with usage counts.

Custom Metadata — Define custom fields (text, number, date, select, boolean, URL), attach to files, search and filter by metadata, auto-extract EXIF data.

Search — Database search out of the box, optional Laravel Scout integration, search by name, tags, metadata, file type, and date range.

Versioning — Upload new versions, view history with changelogs, revert to any previous version, configurable retention with auto-prune.

Export & Import — Export as ZIP with metadata manifest, import from ZIP or local folder with automatic metadata restoration.

Organization — Favorites, recent items, type filters (image, video, document, audio, archive), sort by name/date/size, grid and list views, breadcrumb navigation.

Trash & Recovery — Soft delete with trash folder, restore, permanent delete.

Preview — Full-screen gallery modal with version history, image/video/audio preview, document preview (PDF, Office via Google/Microsoft viewers), keyboard navigation.

UI — Responsive design, dark mode, configurable theme colors, context menu, details panel, drag-and-drop between folders, multi-select with Ctrl/Cmd and Shift.

Visibility & Access Control — Per-file public/private visibility, HMAC-SHA256 hash verification for private URLs, custom authorization callbacks, automatic file movement between storage disks, per-user media scoping.

Cloud Storage — Local, Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Backblaze B2, BunnyCDN.

Developer Tools — 15 singleton services with DI, 16 Laravel events, MediaFileUpload and MediaPickerField form components, MediaFileGrid / MediaFileList / MediaFiles embeddable Livewire components, FilesUploadWidget, HasMediaFiles and InteractsWithMediaCollections traits, MediaAdder fluent builder, typed exceptions, query scopes, per-panel page visibility, configurable navigation.

Keyboard Shortcuts

Requirements

• PHP 8.2+
• Laravel 11+
• Filament 4.0+
• GD or Imagick PHP extension (for thumbnails)
• ZIP PHP extension (for export/import and multi-file download)

Installation

Publish and run migrations:

Publish the config:

Optionally publish views:

Setup

Register the Plugin

Control which pages are registered per panel:

Storage Link

For local storage:

Custom Theme (Tailwind v4)

If your panel uses a custom theme (->viteTheme()), add these @source directives to your theme CSS so Tailwind discovers the package's utility classes:

Then rebuild: npm run build

This is only needed with custom themes. Filament's default theme works without changes.

Configuration

The config file (config/media.php) provides full control over all options.

Feature Flags

Storage Driver

Navigation

Theme Colors

Colors are injected as CSS custom properties (--fm-*) with separate light and dark mode values:

Upload Limits

Thumbnails & Watermarks

Private Files

Search & Versioning

Usage

Media Manager Page

Available at /admin/media (or your panel prefix + /media).

Programmatic Access

All operations use dedicated service classes:

Upload methods return MediaFile directly and throw MediaUploadException on failure.

File Visibility & Access Control

Files have a visibility attribute — public (default) or private. Public files are served via direct storage URL. Private files are served through an authenticated controller with HMAC-SHA256 hash verification.

Changing Visibility

On local storage, files and thumbnails are physically moved between disks.

How Private URLs Work

Public files: /storage/photos/image.jpg Private files: /media/private/{hash}/{id}

The hash is an HMAC-SHA256 of the file ID, keyed to APP_KEY. URLs cannot be guessed or enumerated without the secret key. The controller verifies authentication and authorization before streaming. Append ?download=1 to force download.

Custom Authorization

The callback receives the MediaFile and the authenticated user (or null). Return true to allow, false to deny. Public files bypass the callback.

Per-User Media Scoping

Control which files each user sees in the Media page:

The callback applies a global scope on MediaFile and MediaFolder queries across all views (media, trash, recent, favorites, collections). Not invoked when no user is authenticated.

scopeMediaQueryUsing() controls query-level filtering (what appears in the UI), while authorizeFileAccessUsing() controls file-level download authorization. Use both together for complete access control.

Artisan Commands

Form Components

MediaFileUpload

Pre-configured FileUpload that reads settings from config/media.php:

Automatically resolves MIME types, respects max file size and server limits, uses the configured storage disk, and preserves original filenames.

MediaPickerField

File picker for selecting existing media:

Direct Upload

By default, the field shows a single "Browse Media" button that opens the full media library picker. Enable directUpload() to add a quick "Upload File" option alongside it — the button becomes a dropdown with both choices:

The upload zone supports drag-and-drop and uses the same upload endpoint as the media library. Uploaded files are saved to the root folder and the field state is updated automatically.

To enable direct upload globally for all MediaPickerField instances, set the config default:

You can still override the global default per-field:

Per-Field File Type Control

By default, uploads are validated against the global allowed_mime_types in config/media.php. Two methods let you customize this per field:

Both methods enforce validation on both client-side (browser) and server-side (upload endpoint). Server-side overrides are protected with HMAC-SHA256 signatures to prevent tampering.

Display Styles

The field supports five visual styles via displayStyle():

To set a global default for all fields:

Per-field values always override the config default.

Preview Size

Control the dimensions of the thumbnail preview container (used by thumbnail, integratedLinks, and integratedDropdown styles). The image itself always maintains its natural aspect ratio via object-contain.

Default: 12rem width with aspect-square (192x192px). Any CSS length value works (rem, px, %, etc.). Global defaults can be set in config:

Chip Size

Control the size of the file chips used in compact and dropdown display styles. This affects the thumbnail size, icon size, and text size within each chip.

Available sizes:

Global default can be set in config:

Lightbox Size

Control the maximum dimensions of the full-screen image preview (lightbox) that appears when clicking a thumbnail. By default, the image fills the available viewport.

Global defaults can be set in config:

Lightbox Opacity

Control the backdrop opacity of the lightbox overlay. The value is a percentage from 0 (fully transparent) to 100 (fully opaque). Default: 80.

Global default can be set in config:

Livewire Components

MediaFileGrid

Displays a grid of media files with full context menu. The parent model must use HasMediaFiles:

MediaFileList

Same features as MediaFileGrid in a table/list layout:

MediaFiles

Unified viewer with a toggle between grid and list layouts:

Shared Props

All three components accept the same props:

Context menu keys: preview, download, copy_link, view_parent, rename, alt_text, tags, collections, versions, metadata, export, visibility, favorites, trash.

FilesUploadWidget

Filament widget for adding uploads to any resource page:

Attaching Media to Models

Setup

Uploading

Attaching & Detaching

Querying

URL Attributes on MediaFile

Physical File Deletion

Named Media Collections

For models that need structured, constrained media:

Collections build on the tag system (MediaTag with type='collection'). No additional migrations needed.

Error Handling

Automatic Folder Resolution

When creating a MediaFile without an explicit folder_id, the folder is resolved from the url path:

Auto-resolution only runs when folder_id is 0 or not set. Uses firstOrCreate() internally, so concurrent uploads are safe.

Tags & Collections

Custom Metadata

Search

File Versioning

Export & Import

Exports with metadata include a manifest.json preserving tags, collections, and custom metadata.

Orphan File Management

Manage files in storage that have no database record:

Also available via the Storage Scanner section in Media Settings.

Events

All operations dispatch Laravel events:

File Events

Folder Events

Permissions

Security

• Private File Access — Authenticated controller with customizable authorization callbacks
• HMAC-SHA256 URLs — Private file URLs keyed to the application secret, not guessable
• SSRF Protection — URL downloads validated against internal networks, cloud metadata IPs, and configurable domain allowlists
• XSS Prevention — User content escaped via SafeContentService
• File Validation — Uploads validated for MIME type and size
• Rate Limiting — Private file routes throttled
• CSRF Protection — All Livewire actions protected

Architecture

Services (registered as singletons)

Support Classes

Traits

Livewire Components

Extending

Override any service:

Listen to events:

Testing

Image Gallery Component

A standalone Alpine.js image gallery with lightbox, thumbnails, keyboard navigation, and RTL support. Works with any array of image URLs — no dependency on the media manager models.

Features: main image display, prev/next arrows, thumbnail strip, fullscreen lightbox overlay, keyboard navigation (arrow keys + Escape), image counter badge, RTL-aware arrow direction, no-images placeholder.

Changelog

Please see CHANGELOG for recent changes.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Codenzia
• All Contributors

License

This project uses a dual license:

• Open Source — Available under the MIT License for OSI-approved open source projects.
• Commercial — A commercial license is required for proprietary projects. Visit codenzia.com for options.

See LICENSE.md for full details.