All posts

Mastering Image Optimization in Laravel with Spatie's Media Library

June 5, 2026
Mastering Image Optimization in Laravel with Spatie's Media Library

Introduction to Spatie's Media Library

Handling image uploads, conversions, and responsive generation in Laravel can become complex quickly. Spatie's Media Library package provides a robust solution for associating files with Eloquent models, performing image manipulations, and generating responsive image sets. In this article, we'll dive deep into its capabilities and demonstrate how to integrate it seamlessly into your Laravel application.

Installation and Setup

First, install the package via Composer:

composer require spatie/laravel-medialibrary

Publish the configuration and migration:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"
php artisan migrate

The package allows you to attach multiple media files to any Eloquent model. Your model must implement the HasMedia interface and use the InteractsWithMedia trait.

use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class Post extends Model implements HasMedia
{
    use InteractsWithMedia;
}

Adding Images to Models

You can add media from various sources. Here's how to add an image from an upload request:

$post = Post::create([...]);
$post->addMediaFromRequest('image')->toMediaCollection('images');

You can also add from path or URL:

$post->addMedia($path)->toMediaCollection('images');
$post->addMediaFromUrl($url)->toMediaCollection('images');

Image Conversions and Manipulations

The real power lies in conversions: you can automatically create multiple derived images (thumbnails, responsive sizes, etc.) from a single upload. Define conversions in your model using the registerMediaConversions method:

use Spatie\Image\Manipulations;

public function registerMediaConversions(?Media $media = null): void
{
    $this->addMediaConversion('thumb')
        ->width(150)
        ->height(150)
        ->sharpen(10)
        ->nonQueued();

    $this->addMediaConversion('responsive')
        ->width(1200)
        ->height(800)
        ->format(Manipulations::FORMAT_WEBP)
        ->quality(80)
        ->optimize()
        ->performOnCollections('images');
}

Conversions are queued by default, but you can make them synchronous with nonQueued(). The package supports a wide range of manipulations: resizing, cropping, blurring, orientation, etc.

Responsive Images

For responsive images, the package can generate multiple widths of the same image. Use withResponsiveImages when adding media:

$post->addMedia($path)->withResponsiveImages()->toMediaCollection('images');

This generates a set of images at different widths (e.g., 320, 640, 960, 1280, 1920). In your Blade view, you can use the img component to render responsive images:

// In a Blade view
{{ $post->getFirstMedia('images')->img()->attributes(['class' => 'w-full']) }}

This outputs an <img> tag with srcset and sizes attributes automatically.

Retrieving and Displaying Images

You can retrieve media and their URLs easily:

// Get the first media from the 'images' collection
$media = $post->getFirstMedia('images');

// Get the URL of the original image
$url = $media->getUrl();

// Get the URL of a conversion
$thumbUrl = $media->getUrl('thumb');

// Get the responsive image HTML
$responsiveHtml = $media->img()->attributes(['class' => 'w-full']);

Advanced: Custom Paths and Disk Configuration

You can configure where media files are stored. In config/medialibrary.php, set the default disk:

'disk_name' => env('MEDIA_DISK', 'public'),

For custom paths per model, use the registerMediaPaths method:

public function registerMediaPaths(): void
{
    $this->addMediaPath('/uploads/' . $this->id);
}

Optimizing Images

To reduce file size without noticeable quality loss, enable optimization. Install the required binaries (jpegoptim, optipng, etc.) and configure in config/medialibrary.php:

'image_optimizers' => [
    Spatie\ImageOptimizer\Optimizers\Jpegoptim::class => [
        '-m85', // set maximum quality to 85%
        '--strip-all',  // strip all metadata
        '--all-progressive', // make progressive
    ],
    Spatie\ImageOptimizer\Optimizers\Pngquant::class => [
        '--force', // required parameter for this package
    ],
    Spatie\ImageOptimizer\Optimizers\Optipng::class => [
        '-i0', // result in a non-interlaced (progressive) image
        '-o2',  // optimization level (0-7)
    ],
    Spatie\ImageOptimizer\Optimizers\Svgo::class => [
        '--disable=cleanupNumericValues',
    ],
    Spatie\ImageOptimizer\Optimizers\Gifsicle::class => [
        '-b',
        '-O3',
    ],
    Spatie\ImageOptimizer\Optimizers\Cwebp::class => [
        '-m 6',
        '-pass 10',
        '-mt',
        '-q 80',
    ],
],

Then use optimize() in your conversion:

$this->addMediaConversion('optimized')
    ->width(1920)
    ->optimize()
    ->nonQueued();

Cleaning Up Old Media

When updating an image, you often want to remove the old one. The package provides a convenient method:

$post->clearMediaCollection('images'); // removes all media in that collection
$post->addMedia($newPath)->toMediaCollection('images');

Conclusion

Spatie's Media Library is a powerful tool for managing images in Laravel. With its support for conversions, responsive images, optimization, and flexible storage, you can build a robust image handling system with minimal boilerplate. By following the patterns shown above, you'll be able to implement image uploads, generate thumbnails, and deliver responsive images efficiently.

For further reading, check the official documentation.

Related posts