Download the PHP package sandeep816/smart-media-library without Composer

Smart Media Library

A powerful, reusable media library for Laravel & Filament.

Smart Media Library provides a centralized WordPress-style media management experience for Laravel applications using Filament.

Designed as an independent, reusable package that can be dropped into any Laravel application running Filament 5 without coupling to specific host models or hardcoded panel configurations.

Features

• Central Media Management: Dedicated Filament panel page with searchable, filterable grid and list views.
• Universal MediaPicker Field: Plug-and-play Filament form component supporting both Value Mode (UUID strings/arrays) and Attachment Mode (polymorphic relationships).
• Zero-Coupling Storage: Storage driver agnostic supporting local, public, and private disks (S3, MinIO, etc.) via Laravel's Filesystem abstraction.
• Granular Authorization: Flexible permission hooks supporting Closures, Laravel Model Policies on Media, and Laravel Gate abilities.
• Multi-Panel Ready: Register the plugin across multiple Filament panels with customizable navigation labels, groups, icons, titles, and subheadings.
• Deterministic Ordering: Visual reordering for multiple media selections.
• Strict Type Validation: Restrict selections and uploads to images, videos, documents, or custom MIME types.
• Polymorphic Compatibility: Robust support for integer IDs, BigIncrements, UUIDs, and ULIDs as primary keys on host models.
• Asset Immutability: Detaching or soft-deleting media relationships never deletes physical storage files or central records.
• Image Processing & Derivatives: Built-in conversion pipeline generating thumbnail, small, and medium variants.
• Trash & Restore Lifecycle: Soft-delete support preserving original files and conversion derivatives on deletion with instant restore.
• Public & Private Disk Awareness: Secure URL resolution with automatic privacy safeguards for non-public disks.

Requirements & Compatibility

Declared Constraints (composer.json)

• PHP: ^8.3
• Laravel Framework: ^12.0 || ^13.0
• Filament: ^5.8
• PHP Extensions: gd, exif, fileinfo

Verified Environment Matrix

• Development Host: PHP 8.3.30, Laravel 13.32.0, Filament 5.8.2, MySQL 8.0
• Fresh-Host Clean Installation: PHP 8.5.0, Laravel 13.32.0, Filament 5.8.2, SQLite
• GitHub Actions CI Matrix (Verified):
  • PHP 8.3 + Laravel 12 + Filament 5.8: PASS
  • PHP 8.3 + Laravel 13 + Filament 5.8: PASS
  • PHP 8.4 + Laravel 12 + Filament 5.8: PASS
  • PHP 8.4 + Laravel 13 + Filament 5.8: PASS
  • PHP 8.5 + Laravel 13 + Filament 5.8: PASS

Installation

1. Require the Package

Install the package via Composer:

Local Package Development

If developing or testing locally via a Composer path repository in your host application's composer.json:

Then require the development package:

2. Publish Configuration & Migrations

Publish the package configuration:

Publish and run the database migrations:

(Optional) If you wish to customize Blade views or front-end CSS:

Filament Panel Registration

Register the MediaLibraryPlugin in your Filament Panel Provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

Fluent Plugin Customization

You can customize navigation, page headers, and authorization per panel:

Configuration Reference

The published config/filament-media-library.php file provides extensive options:

Authorization & Security

Smart Media Library provides three tiers of authorization:

1. Fluent Plugin Closure

Define rules directly when registering the plugin in your panel:

Or globally via the MediaAuthorization facade/class:

2. Laravel Model Policy

Define a standard Laravel policy for FilamentMediaLibrary\Models\Media in AuthServiceProvider or auto-discovery:

3. Laravel Gate Abilities

Define abilities prefixed with filament-media-library.:

Supported abilities: view-any, upload, update, trash, restore, delete, select.

MediaPicker Form Component

The MediaPicker form component embeds seamlessly into any Filament Form or Resource.

Value Mode (Single Media)

Stores the Media record's UUID string directly in a model attribute:

Value Mode (Multiple Media)

Stores an array of UUID strings (typically in a JSON or text column):

Attachment Mode (Polymorphic Relationships)

Synchronizes media attachments using the media_attachments table without altering your host model's schema:

Type Constraints & Upload Control

Restrict what users can select or upload:

Interacting with Attachments in Eloquent

Your Eloquent models can optionally use the InteractsWithMediaAttachments trait:

Querying Attached Media:

Managing Attachments Programmatically:

Programmatic Uploading

You can upload files from controllers, CLI commands, or jobs using MediaUploader:

Image Processing & Derivatives

The package includes a built-in, lightweight, zero-dependency image derivative system designed to generate optimized previews and thumbnails without external third-party services or heavy dependencies:

• Original Immutability Guarantee: The original uploaded file is permanently preserved and remains completely immutable. Derivative generation never overwrites or alters original assets.
• Default Presets:
  • thumbnail: 150 × 150 (fit within bounds, aspect-ratio preserved, no upscaling)
  • small: 400 × 400 (fit within bounds, aspect-ratio preserved, no upscaling)
  • medium: 800 × 800 (fit within bounds, aspect-ratio preserved, no upscaling)
• Safe Handling:
  • Animated GIFs: Preserved without rasterization or frame flattening.
  • SVGs: Vector assets are passed through safely without raster distortion.
  • Non-Images: Documents, audio, video, and archives safely skip derivative generation without errors.
  • Orientation & Transparency: Automatically respects EXIF orientation for JPEGs and preserves full 8-bit alpha transparency for PNG and WebP images.
• Public & Private Disk Safety: Derivations are stored on the same disk as the source media. Private disk conversions are never exposed with insecure public URLs; secure temporary URLs or custom controllers can be used identically to original assets.
• Pluggable Architecture: Built on the ImageProcessor interface with an out-of-the-box GdImageProcessor (and easily replaceable with Imagick or custom cloud processors).

Model Conversion API

The Media model provides intuitive methods for accessing derivatives:

Configuration & Custom Presets

Publish filament-media-library.php to customize presets or output formats:

CLI Command: Regenerate Derivatives

You can generate or rebuild derivatives at any time using the Artisan command:

Clean Architecture & Boundary Isolation

• No Application Coupling: Zero runtime references to App\ or specific host database tables.
• Safe Compensating Transactions: If database persistence fails during an upload, storage artifacts are automatically purged.
• Asset Immutability: Detaching attachments or deleting models never deletes physical media files. Central deletion must be explicitly initiated.
• Strict Code Style: 100% PSR-12 compliant, validated by Laravel Pint and covered by automated PHPUnit feature tests.

Independence Disclaimer

Smart Media Library is an independent open-source community package for Filament. It is not affiliated with or endorsed by Filament.

Development & Testing

Smart Media Library includes a standalone test suite powered by Orchestra Testbench and PHPUnit:

License

The MIT License (MIT).