README

Media Library for Laravel

A native Laravel media library: attach files to your Eloquent models in named buckets, or store global media with no owner, on any Laravel disk. Image variants, private signed URLs, deduplicated storage and blur-up placeholders come built in.

Installation

Requires PHP 8.4, Laravel 12 or 13, ext-fileinfo, and ext-imagick or ext-gd for image variants.

composer require roundly-consulting/media-library-for-laravel
php artisan vendor:publish --tag="media-migrations"
php artisan migrate

Usage

Declare the model's buckets once:

use Illuminate\Database\Eloquent\Model;
use RoundlyConsulting\MediaLibrary\Concerns\InteractsWithMedia;
use RoundlyConsulting\MediaLibrary\Contracts\HasMedia;
use RoundlyConsulting\MediaLibrary\Variants\VariantRegistrar;

final class User extends Model implements HasMedia
{
    use InteractsWithMedia;

    public function registerMediaBuckets(): void
    {
        $this->addMediaBucket('avatar')
            ->singleFile()                                   // a new upload replaces the old one
            ->acceptsMimeTypes(['image/jpeg', 'image/png', 'image/webp'])
            ->registerVariants(function (VariantRegistrar $v): void {
                $v->add('thumb')->fit('crop')->width(120)->height(120)->format('webp');
            });
    }
}

Then add and read media through the facade:

use RoundlyConsulting\MediaLibrary\Facades\MediaLibrary;

$avatar = MediaLibrary::for($user);

$media = $avatar->add($request->file('avatar'))->toBucket('avatar');  // validated, stored, thumb rendered

$avatar->url('avatar');              // the original's URL
$avatar->url('avatar', 'thumb');     // the 120×120 WebP variant
$media->placeholderDataUri();        // a tiny blur-up image to show while it loads
$avatar->clear('avatar');            // delete the media and its files

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/media-library-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). Please see License File for more information.

roundly-consulting / media-library-for-laravel

Package info

Security

Fund package maintenance!

Statistics