Image Optimization in Laravel: WebP, Responsive Images, and Automated Conversion

12 min readUpdated on

Images are one of the most common performance bottlenecks in Laravel applications. Storing originals is easy. Resizing on the fly is expensive. Delivering WebP to modern browsers while falling back to JPEG for older ones is the kind of thing that takes a week to build from scratch. spatie/laravel-medialibrary solves the storage and transformation layer, and it processes images with spatie/image (GD or Imagick), so there is no extra image library to wire up. This article covers the full pipeline: upload, conversion, optimization, and serving.

Installation and Configuration

bash
composer require spatie/laravel-medialibrary
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
php artisan migrate

Medialibrary processes images with spatie/image (installed with it), using GD or Imagick. Pick the driver with the image_driver option (below) or the IMAGE_DRIVER env variable:

env
IMAGE_DRIVER=gd
# or: IMAGE_DRIVER=imagick

In config/media-library.php, configure the disk and queue:

php
// config/media-library.php
return [
    'disk_name'                      => env('MEDIA_DISK', 'public'),
    'max_file_size'                  => 1024 * 1024 * 10, // 10 MB
    'queue_connection_name'          => env('QUEUE_CONNECTION', 'redis'),
    'queue_name'                     => 'media-conversions',
    'queue_conversions_by_default'   => env('QUEUE_CONVERSIONS_BY_DEFAULT', true),
    'media_model'                    => Spatie\MediaLibrary\MediaCollections\Models\Media::class,
    'image_driver'                   => env('IMAGE_DRIVER', 'gd'), // 'gd' or 'imagick'
    'path_generator'                 => null, // We'll override this
    'ffmpeg_path'                    => env('FFMPEG_PATH', '/usr/bin/ffmpeg'),
    'ffprobe_path'                   => env('FFPROBE_PATH', '/usr/bin/ffprobe'),
];

HasMedia Trait - Attaching Files to Models

Any Eloquent model can have media. Add HasMedia interface and InteractsWithMedia trait:

php
// app/Models/Post.php
<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;
use Spatie\MediaLibrary\MediaCollections\Models\Media;

class Post extends Model implements HasMedia
{
    use InteractsWithMedia;

    protected $fillable = ['title', 'content', 'status'];

    protected function casts(): array
    {
        return [
            'published_at' => 'datetime',
        ];
    }

    public function registerMediaCollections(): void
    {
        $this->addMediaCollection('featured-image')
            ->singleFile()                          // Only one featured image per post
            ->acceptsMimeTypes(['image/jpeg', 'image/png', 'image/webp'])
            ->withResponsiveImages();               // Auto-generate srcset variants

        $this->addMediaCollection('gallery')
            ->acceptsMimeTypes(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
    }

    public function registerMediaConversions(?Media $media = null): void
    {
        $this->addMediaConversion('thumb')
            ->width(400)
            ->height(300)
            ->sharpen(10)
            ->format('webp')
            ->performOnCollections('featured-image', 'gallery');

        $this->addMediaConversion('hero')
            ->width(1200)
            ->height(630)
            ->format('webp')
            ->withResponsiveImages()
            ->performOnCollections('featured-image');

        $this->addMediaConversion('og-image')
            ->width(1200)
            ->height(630)
            ->format('jpg')
            ->quality(85)
            ->performOnCollections('featured-image');
    }
}

Uploading a file to a collection:

php
// app/Http/Controllers/Api/v1/PostController.php
<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api\v1;

use App\Http\Controllers\Api\ApiController;
use App\Http\Requests\PostStoreRequest;
use App\Http\Resources\PostResource;
use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends ApiController
{
    public function store(PostStoreRequest $request): PostResource
    {
        $post = Post::create($request->validated());

        if ($request->hasFile('featured_image')) {
            $post
                ->addMediaFromRequest('featured_image')
                ->usingName($request->validated('title'))
                ->toMediaCollection('featured-image');
        }

        return new PostResource($post->load('media'));
    }

    public function addGalleryImage(Request $request, Post $post): PostResource
    {
        $request->validate([
            'image' => ['required', 'image', 'max:10240'],
        ]);

        $post
            ->addMediaFromRequest('image')
            ->toMediaCollection('gallery');

        return new PostResource($post->load('media'));
    }
}

Uploading from URL or path (useful for imports):

php
// From URL
$post->addMediaFromUrl('https://example.com/image.jpg')
    ->usingName('Imported Image')
    ->toMediaCollection('gallery');

// From local path
$post->addMedia('/tmp/uploaded-image.jpg')
    ->preservingOriginal()
    ->toMediaCollection('gallery');

// From base64 string
$post->addMediaFromBase64($base64String)
    ->usingFileName('profile.jpg')
    ->toMediaCollection('gallery');

Defining Conversions - Resize, WebP, Thumbnail

Conversions are defined in registerMediaConversions() on the model. Each conversion generates a separate file on disk when the media is added (or when you run the artisan command).

php
// app/Models/Product.php
<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;
use Spatie\MediaLibrary\MediaCollections\Models\Media;
use Spatie\Image\Enums\Fit;

class Product extends Model implements HasMedia
{
    use InteractsWithMedia;

    public function registerMediaCollections(): void
    {
        $this->addMediaCollection('product-images')
            ->acceptsMimeTypes(['image/jpeg', 'image/png', 'image/webp'])
            ->withResponsiveImages();
    }

    public function registerMediaConversions(?Media $media = null): void
    {
        // Small thumbnail for grid views
        $this->addMediaConversion('thumb')
            ->fit(Fit::Crop, 300, 300)
            ->format('webp')
            ->quality(80)
            ->performOnCollections('product-images');

        // Medium for product listings
        $this->addMediaConversion('medium')
            ->fit(Fit::Contain, 600, 600)
            ->background('ffffff')
            ->format('webp')
            ->quality(85)
            ->performOnCollections('product-images');

        // Large for product detail page
        $this->addMediaConversion('large')
            ->fit(Fit::Contain, 1200, 1200)
            ->background('ffffff')
            ->format('webp')
            ->quality(90)
            ->performOnCollections('product-images');

        // JPEG fallback for email/OG tags
        $this->addMediaConversion('og')
            ->fit(Fit::Crop, 1200, 630)
            ->format('jpg')
            ->quality(85)
            ->performOnCollections('product-images');
    }
}

Accessing converted images:

php
$product = Product::find(1);

// Original
$product->getFirstMediaUrl('product-images');

// Specific conversion
$product->getFirstMediaUrl('product-images', 'thumb');
$product->getFirstMediaUrl('product-images', 'medium');

// Get the Media model to access all conversions
$media = $product->getFirstMedia('product-images');
$media->getUrl('thumb');
$media->getUrl('large');
$media->getPath('thumb'); // Disk path, not URL

// Check if conversion is generated
$media->hasGeneratedConversion('thumb'); // bool

Regenerating conversions after changing conversion definitions:

bash
# Regenerate all conversions for all models
php artisan media-library:regenerate

# For a specific model
php artisan media-library:regenerate "App\Models\Product"

# For a specific media ID
php artisan media-library:regenerate --ids=1,2,3

Intervention Image 3.x as the Driver

Intervention Image 3.x is a separate library with GD and Imagick drivers and a clean, chainable, typed API. Medialibrary does not use it: conversions run through spatie/image. If you want it for custom manipulation before adding a file to the library, install intervention/image-laravel yourself and configure its driver (php artisan vendor:publish --provider="Intervention\Image\Laravel\ServiceProvider", then config/image.php):

php
// app/Services/ImageProcessingService.php
<?php

declare(strict_types=1);

namespace App\Services;

use Intervention\Image\Laravel\Facades\Image;

class ImageProcessingService
{
    public function processAvatar(string $sourcePath, string $targetPath): void
    {
        Image::read($sourcePath)
            ->cover(400, 400)                    // Crop to square, centered
            ->sharpen(5)
            ->toWebp(quality: 90)
            ->save($targetPath);
    }

    public function addWatermark(string $sourcePath, string $watermarkPath, string $targetPath): void
    {
        $image     = Image::read($sourcePath);
        $watermark = Image::read($watermarkPath)->scale(width: 200);

        $image
            ->place($watermark, 'bottom-right', offset_x: 15, offset_y: 15)
            ->toJpeg(quality: 85)
            ->save($targetPath);
    }

    public function generatePlaceholder(int $width, int $height, string $color = 'e5e7eb'): string
    {
        return Image::create($width, $height)
            ->fill($color)
            ->toJpeg()
            ->toDataUri();
    }
}

Custom conversion with medialibrary's own spatie/image pipeline:

php
// app/Models/User.php
use Spatie\Image\Enums\Fit;

public function registerMediaConversions(?Media $media = null): void
{
    $this->addMediaConversion('avatar')
        ->fit(Fit::Crop, 200, 200)
        ->format('webp')
        ->quality(85)
        ->performOnCollections('avatars');
}

Custom Disk and Path Strategy

By default, media is stored at {model_type}/{model_id}/{media_id}/{filename}. You can customize this with a PathGenerator:

php
// app/Media/CustomPathGenerator.php
<?php

declare(strict_types=1);

namespace App\Media;

use Spatie\MediaLibrary\MediaCollections\Models\Media;
use Spatie\MediaLibrary\Support\PathGenerator\PathGenerator;

class CustomPathGenerator implements PathGenerator
{
    public function getPath(Media $media): string
    {
        // Organize by collection and date for easier management
        $date = $media->created_at->format('Y/m');
        return "{$media->collection_name}/{$date}/{$media->id}/";
    }

    public function getPathForConversions(Media $media): string
    {
        $date = $media->created_at->format('Y/m');
        return "{$media->collection_name}/{$date}/{$media->id}/conversions/";
    }

    public function getPathForResponsiveImages(Media $media): string
    {
        $date = $media->created_at->format('Y/m');
        return "{$media->collection_name}/{$date}/{$media->id}/responsive/";
    }
}

Register in config/media-library.php:

php
'path_generator' => \App\Media\CustomPathGenerator::class,

Using S3 for production:

php
// config/filesystems.php
's3' => [
    'driver'   => 's3',
    'key'      => env('AWS_ACCESS_KEY_ID'),
    'secret'   => env('AWS_SECRET_ACCESS_KEY'),
    'region'   => env('AWS_DEFAULT_REGION'),
    'bucket'   => env('AWS_BUCKET'),
    'url'      => env('AWS_URL'),
    'endpoint' => env('AWS_ENDPOINT'),
    'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
],
php
// .env
MEDIA_DISK=s3

With the s3 disk, all media files and conversions are stored in S3 and URLs are built from the disk's url setting. Make the bucket public (or put a CDN in front of it) for public URLs; for private buckets use getTemporaryUrl().

Generating Conversions in Queue Jobs

With 'queue_conversions_by_default' => true, conversions are generated asynchronously by a queue worker. This means after upload, the original is immediately available but conversions take a moment.

The queue job is Spatie\MediaLibrary\Conversions\Jobs\PerformConversionsJob. Run a dedicated worker for it:

bash
php artisan queue:work redis --queue=media-conversions

Checking conversion status from the API:

php
// app/Http/Resources/MediaResource.php
<?php

declare(strict_types=1);

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class MediaResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'          => $this->id,
            'name'        => $this->name,
            'file_name'   => $this->file_name,
            'mime_type'   => $this->mime_type,
            'size'        => $this->size,
            'original'    => $this->getUrl(),
            'conversions' => [
                'thumb'  => $this->hasGeneratedConversion('thumb')
                    ? $this->getUrl('thumb')
                    : null,
                'medium' => $this->hasGeneratedConversion('medium')
                    ? $this->getUrl('medium')
                    : null,
                'large'  => $this->hasGeneratedConversion('large')
                    ? $this->getUrl('large')
                    : null,
            ],
            'conversions_ready' => $this->hasGeneratedConversion('thumb')
                && $this->hasGeneratedConversion('medium'),
        ];
    }
}

Manually dispatching conversions:

php
// Force immediate conversion generation (bypass the queue):
// mark the conversion with ->nonQueued() in registerMediaConversions()

// Or dispatch the job yourself to a specific queue
use Spatie\MediaLibrary\Conversions\ConversionCollection;
use Spatie\MediaLibrary\Conversions\Jobs\PerformConversionsJob;

PerformConversionsJob::dispatch(ConversionCollection::createForMedia($media), $media)
    ->onQueue('high-priority');

Responsive Images - srcset Without Extra Work

Adding ->withResponsiveImages() to a collection generates multiple size variants of the original for srcset; conversions opt in separately with ->withResponsiveImages() on the conversion (the hero conversion above does, which is what img('hero') and getSrcset('hero') rely on). Browsers then download the appropriate size based on the viewport and device pixel ratio.

php
// In registerMediaCollections()
$this->addMediaCollection('featured-image')
    ->withResponsiveImages();

The variant widths are chosen by the width calculator (by default each is about 30% smaller in file size than the previous one), so they depend on the original image. They're stored alongside the original and conversions.

Using responsive images in Blade:

blade
{{-- resources/views/posts/show.blade.php --}}
@if($post->hasMedia('featured-image'))
    {{ $post->getFirstMedia('featured-image')->img('hero', ['class' => 'w-full', 'alt' => $post->title]) }}
@endif

This generates markup along these lines (widths and file names are illustrative; the real ones come from the width calculator):

html
<img
    src="https://cdn.example.com/featured-image/2026/03/1/hero.webp"
    srcset="
        https://cdn.example.com/featured-image/2026/03/1/responsive/hero___340.webp 340w,
        https://cdn.example.com/featured-image/2026/03/1/responsive/hero___510.webp 510w,
        https://cdn.example.com/featured-image/2026/03/1/responsive/hero___680.webp 680w
    "
    sizes="(max-width: 768px) 100vw, 1200px"
    class="w-full"
    alt="My Post Title"
>

In API responses (for React/Vue frontends):

php
// app/Http/Resources/PostResource.php
'featured_image' => $this->getFirstMedia('featured-image') ? [
    'url'      => $this->getFirstMediaUrl('featured-image', 'hero'),
    'thumb'    => $this->getFirstMediaUrl('featured-image', 'thumb'),
    'srcset'   => $this->getFirstMedia('featured-image')->getSrcset('hero'),
    'alt'      => $this->title,
] : null,

Senior Twist: WebP with JPEG Fallback - Serving the Right Format

WebP offers 25-35% smaller file sizes than JPEG at the same visual quality. But some older browsers (and some email clients) don't support WebP. The solution: generate both formats and serve the right one.

Strategy 1: Generate both conversions and choose in code:

php
// In registerMediaConversions()
$this->addMediaConversion('hero-webp')
    ->width(1200)
    ->height(630)
    ->format('webp')
    ->quality(85)
    ->performOnCollections('featured-image');

$this->addMediaConversion('hero-jpg')
    ->width(1200)
    ->height(630)
    ->format('jpg')
    ->quality(85)
    ->performOnCollections('featured-image');
php
// In API resource - let the client pick
'featured_image' => [
    'webp' => $this->getFirstMediaUrl('featured-image', 'hero-webp'),
    'jpg'  => $this->getFirstMediaUrl('featured-image', 'hero-jpg'),
],

The React/Vue frontend uses the <picture> element:

html
<picture>
    <source type="image/webp" :srcset="post.featured_image.webp" />
    <img :src="post.featured_image.jpg" :alt="post.title" />
</picture>

Strategy 2: Serve via Nginx with Accept header negotiation:

nginx
# nginx.conf
location ~* \.(jpg|jpeg|png)$ {
    add_header Vary Accept;

    # Check if WebP version exists and browser accepts WebP
    if ($http_accept ~* "webp") {
        rewrite ^(.*)\.(jpg|jpeg|png)$ $1.webp break;
    }
}

This only works if a .webp file sits next to each original under the same name. Medialibrary does not do that: conversions are stored in a conversions/ directory as {name}-{conversion}.webp, so you would need to adjust the rewrite target or write side-by-side files yourself.

Strategy 3: Return the right format from the controller based on Accept header:

php
// app/Http/Controllers/Api/v1/MediaController.php
<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api\v1;

use App\Http\Controllers\Api\ApiController;
use App\Models\Post;
use Illuminate\Http\Request;

class MediaController extends ApiController
{
    public function featuredImage(Request $request, Post $post): \Illuminate\Http\JsonResponse
    {
        $acceptsWebP = str_contains($request->header('Accept', ''), 'image/webp');

        $conversion = $acceptsWebP ? 'hero-webp' : 'hero-jpg';

        return $this->success('Image URL', [
            'url'    => $post->getFirstMediaUrl('featured-image', $conversion),
            'format' => $acceptsWebP ? 'webp' : 'jpg',
        ]);
    }
}

Image optimization tips:

  • Use ->quality(80) for WebP - 80 is visually lossless for most images
  • Use ->quality(85) for JPEG - 85 is the sweet spot for quality vs size
  • Use ->sharpen(5) after resizing - resizing softens images, a light sharpen compensates
  • Use ->fit(Fit::Crop, $width, $height) for thumbnails where dimensions must be exact, Fit::Contain for product images to avoid cropping
  • Enable ->withResponsiveImages() only for hero/featured images - generating 8 srcset variants for each gallery image multiplies storage costs

Summary

  • Install spatie/laravel-medialibrary; set image_driver to GD or Imagick based on server capabilities
  • Add HasMedia interface + InteractsWithMedia trait to any model; define collections in registerMediaCollections() and conversions in registerMediaConversions()
  • Use ->singleFile() for profile pictures and featured images; omit it for gallery collections
  • Define named conversions per collection (thumb, medium, large, og) with explicit format and quality - don't rely on defaults
  • Set 'queue_conversions_by_default' => true and run a dedicated media-conversions queue worker; expose hasGeneratedConversion() in API responses so clients know when to render
  • Use ->withResponsiveImages() on hero/featured image collections to get srcset for free
  • Generate both webp and jpg conversions; use <picture> on the frontend or Nginx Accept header negotiation to serve the right format
  • Use a custom PathGenerator to organize media by date instead of the default model-type/model-id structure

Related articles

Existing system support

Need help with a live application?

I help companies improve live systems, clean up delivery workflows, and ship new features without adding avoidable complexity.

Comments (0)
Sign in to leave a comment

You need to be signed in to add a comment.

Login

Need someone to take responsibility for the next step?

Let’s talk about your project and define a scope that actually makes sense for your goals.