Laravel Media

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

Automatic Installation (Recommended)

Run the install command to publish and run the migrations:

php artisan media:install

Manual Installation

Alternatively, you can install manually:

1. Publish the migrations:

php artisan vendor:publish --provider="Rdcstarr\Media\MediaServiceProvider" --tag="laravel-media-migrations"

2. Run the migrations:

php artisan migrate

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. ⚖️