Are you tired of struggling with image uploads in your Laravel projects? Want a simple, efficient way to manage all your media files – from photos to documents? Look no further! Spatie's Laravel Media Library is here to save the day. This amazing package simplifies everything, allowing you to easily upload, store, and manipulate media files. And guess what? It's completely free!

In this blog post, we'll walk you through setting up and using this powerful library, making your Laravel app more robust and user-friendly.

Why Spatie Media Library?

Before we dive in, let's quickly understand why so many Laravel developers love this package:

• Effortless Uploads: Add files to your models with just a few lines of code.

• Automatic Conversions: Create different versions of your images (like thumbnails, webp for performance) on the fly.

• Organized Storage: Keeps your media files neatly organized and associated with your models.

• Flexible: Works with various storage disks (local, S3, etc.).

Ready to get started? Let's go!

Step 1: Installation – Getting the Package Ready

First things first, we need to install the Spatie Media Library package into your Laravel project. Open your terminal and run these commands:

composer require "spatie/laravel-medialibrary"

Once Composer finishes, you'll need to publish the migrations and then run them. These migrations will create the necessary tables in your database to store information about your media files.

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

php artisan migrate

Optional: Publishing the Config File

If you want to customize the Media Library's settings (like disk names, custom paths, etc.), you can publish its configuration file:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-config"

Finally, ensure your storage folder is linked. This is crucial for local storage to work correctly.

php artisan storage:link

Great! The package is now installed and configured.

Step 2: Preparing Your Model for Media

Now, let's tell your Laravel model that it can handle media files. For any model you want to associate media with (e.g., a Post model for blog post images), you need to implement the HasMedia interface and use the InteractsWithMedia trait.

Here's how you do it for a Post model:

// app/Models/Post.php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\MediaLibrary\HasMedia; // for spatie Media
use Spatie\MediaLibrary\InteractsWithMedia;  // for spatie Media
use Spatie\MediaLibrary\MediaCollections\Models\Media; // Don't forget this for conversions!

// make sure to implements HasMedia trait

class Post extends Model implements HasMedia
{
    use InteractsWithMedia; // Make sure to use this trait!
    
    // this will auto load realation with eager load
     protected $with = ['media'];
  

    /**
     * Register the media conversions.
     * This is where you define different sizes/formats for your images.
     */
    public function registerMediaConversions(Media $media = null): void
    {
        // Convert all images to webp format for better performance
        $this->addMediaConversion('webp')
             ->format('webp')
             ->nonQueued(); // Use nonQueued for smaller apps, or queued for larger ones

        // Create a thumbnail version (optional but very useful!)
        $this->addMediaConversion('thumb')
            ->format('webp') // Also make the thumbnail webp
            ->width(300)
            ->height(200)
            ->sharpen(10) // Make it a bit sharper
            ->nonQueued();
    }
}

In the registerMediaConversions method, we've defined two conversions:

• webp: This will convert your uploaded images into the modern WebP format, which is excellent for web performance.

• thumb: This creates a smaller thumbnail version, perfect for listings or previews.

Step 3: Uploading and Managing Media in Your Controller

Now let's see how to handle image uploads from your forms.

Creating a New Post with an Image

In your controller (e.g., PostController@store), you'll handle the file upload.
 

public function store(Request $request)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'body' => 'required|string',
            'image' => 'nullable|image|mimes:jpeg,png,jpg,gif,svg|max:2048', // Validate image
        ]);

        $post = Post::create([
            'title' => $request->title,
            'body' => $request->body,
        ]);

        // If an image is present, add it to the 'post' media collection
        if ($request->hasFile('image')) {
            $post->addMediaFromRequest('image')
                ->toMediaCollection('image'); // 'post' is the name of your media collection
        }

        return redirect()->route('posts.index')->with('success', 'Post created successfully!');
    }

Updating an Existing Post with a New Image

When editing a post, you might want to replace the old image with a new one. The clearMediaCollection method is perfect for this.

 public function update(Request $request, Post $post)
    {
        $request->validate([
            'title' => 'required|string|max:255',
            'body' => 'required|string',
            'image' => 'nullable|image|mimes:jpeg,png,jpg,gif,svg|max:2048', // Validate image
        ]);

        $post->update([
            'title' => $request->title,
            'body' => $request->body,
        ]);

        // If a new image is uploaded, clear the old one and add the new one
        if ($request->hasFile('image')) {
            $post->clearMediaCollection('image'); // This removes all media from the 'post' collection
            $post->addMediaFromRequest('image')
                ->toMediaCollection('image'); // Then add the new image
        }

        return redirect()->route('posts.index')->with('success', 'Post updated successfully!');
    }

Remember to have an enctype="multipart/form-data" attribute on your HTML form tag for file uploads to work!

<form action="/posts" method="POST" enctype="multipart/form-data">
    @csrf
    <input type="text" name="title" placeholder="Post Title">
    <textarea name="body" placeholder="Post Content"></textarea>
    <input type="file" name="image">
    <button type="submit">Save Post</button>
</form>

Step 4: Displaying Your Media in Blade

Now for the exciting part – showing off your images! Spatie Media Library provides handy methods to retrieve the URLs of your media files, including the converted versions.

<h3>Thumbnail:</h3>
<img src="{{ $post->getFirstMediaUrl('image', 'thumb') }}" alt="{{ $post->title }} ">


<h3>Optimized WebP Image:</h3>
<img src="{{ $post->getFirstMediaUrl('image', 'webp') }}" alt="{{ $post->title }}">


<h3>Original Image:</h3>
<img src="{{ $post->getFirstMediaUrl('image') }}" alt="{{ $post->title }}">

• $post->getFirstMediaUrl('image', 'thumb'): This gives you the URL for the 'thumb' conversion from the 'post' collection.

• $post->getFirstMediaUrl('image', 'webp'): This gives you the URL for the 'webp' conversion.

• $post->getFirstMediaUrl('image'): This gives you the URL for the original file (without any specific conversion).

And There You Have It!

You've successfully integrated the Spatie Laravel Media Library into your application! Now you can manage images and other media files like a pro. This package saves tons of development time and keeps your codebase clean. Experiment with different conversions, explore more features in the official documentation, and make your Laravel apps even better!

Happy coding!

Resources 📚

For more detailed information and advanced usage, be sure to check out the official documentation and the GitHub repository for the Spatie Laravel Media Library.

• Official Documentation: https://spatie.be/docs/laravel-medialibrary

• GitHub Repository: https://github.com/spatie/laravel-medialibrary