Laravel Media Library

The Laravel MediaLibrary uses a responsive images technique to optimize loading. It works by:

1. Rendering an <img> tag with multiple srcset values.
2. Using an initial sizes="1px" attribute to render an inline base64-encoded SVG placeholder first.
3. Using JavaScript to update the sizes attribute to the actual width of the image in the layout once the page has loaded.
4. Using a vw (viewport width) value for the updated width, which allows the browser to load larger image versions automatically when the browser window is upscaled.

To see this in action, you can throttle your network in Chrome and disable the cache, or resize your browser window to trigger different image loads.

Once your model is set up, you can generate and access derived images (such as thumbnails) for images, videos, and PDFs using the getUrl() method on a media instance.

$yourModel->getMedia('images')->first()->getUrl('thumb');

When upgrading to v11, note the following breaking changes:

• Image Conversions: The package now uses Image v3. You must update your image conversion syntax to match the new requirements. Refer to the Spatie Image v3 documentation.
• Event Names: All event names now include an Event suffix. For example, Spatie\MediaLibrary\MediaCollections\Events\MediaHasBeenAdded has been renamed to Spatie\MediaLibrary\MediaCollections\Events\MediaHasBeenAddedEvent.

Media Library can automatically optimize converted images if specific binaries are installed on your system. Supported tools include jpegoptim, optipng, pngquant, svgo, gifsicle, and avifenc.

Ubuntu

sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
npm install -g svgo

Or using snap for svgo:

sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
sudo snap install svgo

Alpine Linux

apk add jpegoptim optipng pngquant gifsicle libavif-apps
npm install -g svgo

MacOS (Homebrew)

brew install jpegoptim optipng pngquant svgo gifsicle libavif

Use deferred() to schedule a conversion to run after the HTTP response has been sent to the browser. This uses Laravel's defer() helper. This is ideal for tasks like generating avatars where you want to avoid blocking the upload request, but the task is too heavy for a standard synchronous request.

Requirement: Requires Laravel 11.23 or higher. For older versions, use queued() or nonQueued().

public function registerMediaConversions(?Media $media = null): void
{
    $this->addMediaConversion('thumb')
            ->width(368)
            ->height(232)
            ->deferred();
}

To associate a file located on your local filesystem with a model, use the addMedia() method followed by toMediaCollection(). By default, the file will be moved to your configured media library disk.

$yourModel = YourModel::find(1);
$yourModel
   ->addMedia($pathToFile)
   ->toMediaCollection();

To make a custom image generator available across your entire application, add the class name to the image_generators array in your config/laravel-medialibrary.php configuration file.

// in config/laravel-medialibrary.php
'image_generators' => [
    // ...
    YourImageGenerator::class,
],

To install the base Media Library package via Composer, run the following command:

composer require "spatie/laravel-medialibrary"

Note: If you have a license for Media Library Pro, you should install spatie/laravel-media-library-pro instead.

By default, responsive image files are named using the format: {original-file-name-without-extension}___{name-of-the-conversion}_{width}_{height}.{extension}.

You can customize this by implementing a custom FileNamer class. Note that when customizing responsive filenames, you can only control the prefix of the name, as the library requires specific suffixes (conversion name, width, and height) to process responsive images correctly.