Spatie Laravel Media Library

Laravel Media Library, Eloquent modellerinizi her türlü dosya (görseller, PDF'ler, videolar, belgeler vb.) ile ilişkilendirmenizi, otomatik görsel boyutlandırma/dönüştürme (thumbnail, WebP, responsive images) yapmanızı ve dosyaları yerel diskte veya AWS S3/Cloudflare R2 gibi bulut depolama alanlarında yönetmenizi sağlayan kapsamlı bir medya yönetim aracıdır.

Neden Tercih Edilmeli?

• Model Bağımlı Medya: Modeller silindiğinde bağlı dosyaların ve dönüşümlerin otomatik temizlenmesini sağlar.
• Otomatik Görsel Dönüşümleri: Orijinal görsel yüklendiğinde otomatik olarak thumbnail, avatar, webp ve responsive varyasyonlarını üretir.
• Koleksiyonlar (Collections): Bir modele birden fazla koleksiyon (avatar, gallery, documents) tanımlayarak dosyaları organize eder.
• Kuyruk Entegrasyonu: Büyük dosya işleme ve görsel manipülasyonlarını arka planda kuyruk worker'larına devreder.
• Çoklu Disk & Bulut Desteği: S3, DigitalOcean Spaces, MinIO veya yerel depolama arasında tek satırla geçiş imkanı sunar.

Kurulum

Composer ile paketi yükleyin:

composer require spatie/laravel-medialibrary

Migration ve yapılandırma dosyasını yayınlayıp çalıştırın:

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

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

Model Yapılandırması

Modelinize HasMedia arayüzünü ve InteractsWithMedia trait'ini ekleyin:

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;

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

        $this->addMediaConversion('webp-preview')
            ->format('webp')
            ->width(800)
            ->height(600);
    }
}

Temel Kullanım

Dosya Yükleme ve İlişkilendirme

$post = Post::find(1);

// HTTP İstek dosyasından yükleme
$post->addMediaFromRequest('cover_image')
    ->toMediaCollection('covers');

// Dosya yolu veya URL üzerinden yükleme
$post->addMedia('/tmp/document.pdf')
    ->toMediaCollection('documents');

$post->addMediaFromUrl('https://example.com/photo.jpg')
    ->toMediaCollection('gallery');

Medya URL ve HTML Çıktısı Alma

<!-- Orijinal Görsel URL -->
<img src="{{ $post->getFirstMediaUrl('covers') }}" alt="{{ $post->title }}">

<!-- Dönüştürülmüş Thumbnail URL -->
<img src="{{ $post->getFirstMediaUrl('covers', 'thumb') }}" alt="Küçük Resim">

<!-- WebP Dönüşümü -->
<img src="{{ $post->getFirstMediaUrl('covers', 'webp-preview') }}" alt="WebP Önizleme">

<!-- Responsive Görsel Çıktısı -->
{{ $post->getFirstMedia('covers')?->img('thumb', ['class' => 'rounded-lg shadow']) }}

Çoklu Dosya Koleksiyonları ve Silme

// Galeriye birden fazla görsel ekleme
foreach ($request->file('photos') as $photo) {
    $post->addMedia($photo)->toMediaCollection('gallery');
}

// Tüm galeri görsellerini listeleme
foreach ($post->getMedia('gallery') as $media) {
    echo $media->getUrl();
}

// Koleksiyonu temizleme
$post->clearMediaCollection('covers');