README

A flexible and powerful media management package for Laravel that handles images, videos, audio files, and documents with ease. Features automatic image optimization, multiple format support (WebP, AVIF), dynamic collections, and seamless Eloquent integration.

Features

🖼️ Image Processing: Automatic resizing, cropping, and format conversion (WebP, AVIF, PNG, JPG)
📁 Multiple File Types: Support for images, videos, audio, and generic files
🔗 Model-Centric Design: Tightly integrated with Eloquent models
📦 Collections: Organize media files into named collections
🎯 Flexible Configuration: Per-collection settings for disk, path, dimensions, and more
🗑️ Automatic Cleanup: Files are deleted when models or media records are removed
🔄 Soft Delete Support: Respects soft deletes on parent models
📤 URL Support: Upload files directly from URLs
🏷️ Metadata: Store custom metadata with each media file
⚡ Events: Listen to media created, updated, and deleted events

Installation

You can install the package via composer:

composer require rdcstarr/laravel-media

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-media-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-media-config"

Usage

Setup Model

use Rdcstarr\Media\Traits\HasMedia;
use Rdcstarr\Media\Enums\{MediaType, ImageExtension};

class Product extends Model
{
    use HasMedia;

    public function mediaCollection(): array
    {
        return [
            'thumbnail' => [
                'type' => MediaType::Image,
                'width' => 300,
                'height' => 300,
                'extensions' => [ImageExtension::WEBP => 90, ImageExtension::JPG => 85],
            ],
            'gallery' => [
                'type' => MediaType::Image,
                'width' => 1200,
                'extensions' => [ImageExtension::WEBP => 90, ImageExtension::AVIF => 80],
            ],
        ];
    }
}

Upload & Retrieve

// Upload
$product->attachMedia()->file($request->file('image'))->addToCollection('gallery');
$product->attachMedia()->file('https://example.com/image.jpg')->replaceExisting()->addToCollection('thumbnail');

// Retrieve
$url = $product->getMediaUrl('thumbnail', 'webp');
$product->getMediaThumbnailUrl('webp');  // Magic method
$product->clearMediaCollection('gallery', ['jpg']);  // Delete

Configuration

Collection Options

[
    'type' => MediaType::Image,           // Media type (Image|Video|Audio|File)
    'disk' => 'public',                   // Storage disk
    'path' => '{model}/{collection}',     // Path with placeholders: {ulid}, {uuid}, {model}, {collection}
    'name' => '{ulid}',                   // Filename pattern
    'visibility' => 'public',             // File visibility
    'width' => 1200,                      // Image width (px)
    'height' => 800,                      // Image height (px)
    'fit' => 'contain',                   // Fit mode (contain|cover|fill)
    'extensions' => [                     // Formats with quality
        ImageExtension::WEBP => 90,
        ImageExtension::AVIF => 80,
    ],
]

Enums (Type-Safe)

MediaType: Image, Video, Audio, File
ImageExtension: JPEG, JPG, PNG, WEBP, AVIF, GIF, SVG, BMP, TIFF
VideoExtension: MP4, WEBM, OGG, AVI, MOV, WMV, FLV, MKV, M4V
AudioExtension: MP3, WAV, OGG, M4A, AAC, FLAC, WMA, OPUS

Events & Architecture

Events: MediaCreated, MediaUpdated, MediaDeleted

Model-centric design: All operations require a model instance, ensuring type safety, clear ownership, and automatic cleanup of files when models or media are deleted.

🧪 Testing

composer test

📖 Resources

Changelog for more information on what has changed recently. ✍️

👥 Credits

Rdcstarr 🙌

📜 License

License for more information. ⚖️

rdcstarr / laravel-media

Maintainers

Details