Laravel 13.20 Görüntü İşleme: Üretim Rehberi

Bu makale, Laravel 13.20’de yer alan Illuminate\Image bileşeni ve Image façade ile resim işlemenin nasıl yapılacağına dair bir kılavuz niteliğindedir. Makale, Laravel Framework v13.20.0 üzerinde gerçekleştirilmiştir.

Resim yönetimi genellikle basit kalmaz. Bir avatar yüklemesi, thumbnail, WebP kopyası, bir depolama politikası, bir doğrulama kuralı ve sonuçta bir kuyruğa dönüşebilir.

Laravel 13.20, 14 Temmuz 2026’da piyasaya sürüldü ve bu çalışmaya yeni bir yerleşim sağladı. Resim işleme, istekler, dosya sistemi diskleri, yapılandırma ve Laravel’in konteyneri ile bağlanırken dönüştürme boru hatlarını değişmez tutar.

Birinci Taraf Resim İşlemenin Anlamı

Laravel uygulamaları yıllardır Intervention Image, özel sarmalayıcılar ve dış resim hizmetleri kullanmaktadır. Laravel 13.20, Intervention Image’ı ortadan kaldırmaz. Yerleşik GD ve Imagick sürücüleri altında intervention/image:^4.0 kullanır.

Birinci taraf kısmı, Laravel’e yönelik API’dir:

use Illuminate\Support\Facades\Image;
use RuntimeException;

$thumbnail = Image::fromPath(storage_path('app/source/photo.jpg'))
    ->orient()
    ->cover(640, 360)
    ->toWebp()
    ->quality(80);

$storedPath = $thumbnail->store('thumbnails', 'public');

if ($storedPath === false) {
    throw new RuntimeException('The thumbnail could not be stored.');
}

Bu zincir, dört konuyu tanımlar:

1. Kaynağı tembel yükleme.
2. Dönüşümleri kaydedin.
3. Çıktı formatı ve kalitesini seçin.
4. Sonucu Laravel’in dosya sistemi üzerinden işleyin ve depolayın.

Yerleşik sürücüler GD ve Imagick’i destekler. GD varsayılandır. Varsayılan işleme kalitesi, başka bir değer seçilmediği sürece 70’dir.

Sürücüyü Yükleyin ve Yapılandırın

Laravel 13.20 ve görüntü bileşeni için PHP 8.3 veya daha yeni bir sürüm gereklidir. Önerilen işleme bağımlılığını yükleyin:

composer require intervention/image:^4.0

Çalışma zamanınız ayrıca seçilen sürücü için uzantıya ihtiyaç duyar:

• GD için ext-gd.
• Imagick için ext-imagick ve ImageMagick sistem kütüphanesi.

Resim yapılandırması varsayılan olarak GD kullanır:

return [
    'default' => env('IMAGE_DRIVER', 'gd'),
];

Imagick’i uygulama varsayılanı olarak kullanmak için:

IMAGE_DRIVER=imagick

Bir bireysel boru hattı, genel yapılandırmayı değiştirmeden farklı bir sürücü seçebilir:

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/photo.jpg'));

$gdVariant = $source->usingGd()->cover(400, 400);
$imagickVariant = $source->usingImagick()->cover(400, 400);

Her iki sürücüyü de, dağıttığınız konteyner içinde aynı temsilci dosyalarla test edin. Çıktı boyutu, bellek kullanımı ve işleme süresi, kaynak malzeme ve uzantı yapısına bağlıdır.

Desteklenen Kaynaklardan Resimler Oluşturma

Bileşen, istek yüklemelerini, yerel yolları, URL’leri, ham baytları, Base64 dizelerini ve Laravel depolama yollarını kabul eder.

İstek Yüklemeleri

Bir yüklemeyi sorarak resim sürücüsünün bunun için kodlamasını istemeden önce doğrulayın:

use Illuminate\Http\Request;

public function store(Request $request)
{
    $request->validate([
        'avatar' => [
            'required',
            'image',
            'mimes:jpeg,png,webp',
            'max:5120',
            'dimensions:min_width=200,min_height=200,max_width=6000,max_height=6000',
        ],
    ]);

    $image = $request->image('avatar');

    abort_if($image === null, 422, 'A valid avatar image is required.');

    // Build the output pipeline from $image.
}

$request->image('avatar') bir dosya yüklendiğinde bir Illuminate\Image\Image nesnesi döner. Bunu yapmadığı durumlarda null döner.

Diğer Giriş Noktaları

use Illuminate\Support\Facades\Image;
use Illuminate\Support\Facades\Storage;
use RuntimeException;

$binaryContents = file_get_contents(storage_path('app/source/photo.jpg'));

if ($binaryContents === false) {
    throw new RuntimeException('The source image could not be read.');
}

$base64Contents = base64_encode($binaryContents);

$fromPath = Image::fromPath(storage_path('app/source/photo.jpg'));
$fromUrl = Image::fromUrl('https://assets.example.test/photo.jpg');
$fromBytes = Image::fromBytes($binaryContents);
$fromBase64 = Image::fromBase64($base64Contents);
$fromStorage = Image::fromStorage('originals/photo.jpg', 's3');
$fromDisk = Storage::disk('s3')->image('originals/photo.jpg');

Çoğu kaynak tembel. Laravel, çıktıyı veya meta verileri talep ettiğinizde gerçek içerikleri okur veya indirir.

Güvenilmeyen bir kullanıcı URL’sini doğrudan fromUrl() fonksiyonuna iletmeyin. Kontrol altındaki bir indirgici, yönlendirmeleri ve yanıt boyutlarını sınırlamalı, özel ağ hedeflerini reddetmeli, kısa bir zaman aşımı belirlemeli ve önce medya türünü doğrulamalıdır.

Değişmezlik, Varyantların Nasıl Oluştuğunu Değiştirir

Her dönüşüm ve çıktı seçeneği resmi klonlar. Kaynak boru hattı değişmez kalır.

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/product.jpg'))->orient();

$thumbnail = $source->cover(400, 400)->toWebp()->quality(78);

$detail = $source->scale(['width' => 1600])->toWebp()->quality(84);

$openGraph = $source->cover(1200, 630)->toJpg()->quality(85);

Bu, branşlaşmayı öngörülebilir yapar. cover() eklemek $thumbnail‘a $detail‘i kazara yeniden boyutlandırmaz.

Bir ilişkili sınır vardır: bir Image nesnesi serileştirilemez. Bunu kuyruk işine koymayın. Önce orijinalini saklayın, ardından depolama yolunu veya kendi varlık tanımlayıcınızı iletin.

Yerleşime Uygun Dönüşümü Seçin

Laravel 13.20, şu dönüşümleri sunar:

Kesin kartlar ve avatarlar için cover()‘ı tercih edin, bütün ürün veya logonun görünür olması gerektiğinde contain()‘ı kullanın ve responsive genişlik varyantları için scale()‘ı tercih edin.

Dönüştür ve Çıktıyı İncele

Laravel 13.20, açık WebP ve JPEG çıktı yöntemleri sunar:

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/product.jpg'));

$webp = $source->scale(['width' => 1200])->toWebp()->quality(82)->optimize();

$jpeg = $source->cover(1200, 630)->toJpg()->quality(85);

toJpeg() ayrıca toJpg() için bir takma ad olarak da kullanılabilir.

Yukarıda oluşturulan $webp boru hattı ile işlenmiş çıktıyı incelemek veya dışa aktarmak için aşağıdaki yöntemleri kullanabilirsiniz:

$width = $webp->width();
$height = $webp->height();
$dimensions = $webp->dimensions();
$mimeType = $webp->mimeType();
$extension = $webp->extension();
$bytes = $webp->toBytes();
$base64 = $webp->toBase64();
$dataUri = $webp->toDataUri();

Dosya yollarını ve resim meta verilerini veritabanında saklayın, Image nesnesini veya büyük bir Base64 değerini değil.

Üretim Avatar İş Akışı

Güvenli bir iş akışı, yeni dosya ve veritabanı güncellemesi başarılı oluncaya kadar önceki varlığı korur. Aşağıdaki kısa örnek, önemli sınırı gösterir:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
use RuntimeException;
use Throwable;

public function updateAvatar(Request $request)
{
    $request->validate([
        'avatar' => [
            'required',
            'image',
            'mimes:jpeg,png,webp',
            'max:5120',
            'dimensions:min_width=200,min_height=200,max_width=6000,max_height=6000',
        ],
    ]);

    $source = $request->image('avatar');

    abort_if($source === null, 422, 'A valid avatar image is required.');

    $user = $request->user();

    abort_if($user === null, 401);

    $path = "avatars/{$user->getKey()}-".Str::uuid().'.webp';

    $stored = $source->orient()->cover(512, 512)->toWebp()->quality(82)->storeAs($path, 'public');

    if ($stored === false) {
        throw new RuntimeException('The avatar could not be stored.');
    }

    try {
        DB::transaction(function () use ($user, $path): void {
            $user->forceFill(['avatar_path' => $path])->save();
        });
    } catch (Throwable $exception) {
        Storage::disk('public')->delete($path);
        throw $exception;
    }

    return back()->with('status', 'Avatar updated.');
}

Tam bir değiştirme iş akışında, işlemin başarılı olduğundan emin oluncaya kadar eski yolu saklayın ve yeni yol aktif olduktan sonra silin. Versiyonlanmış dosya adları, başarısız bir yazmanın son geçerli varlığı yok etmesini engeller.

Maliyetli İşleri Kuyruğa Taşıyın

Küçük avatarlar istek sırasında işlenebilir. Büyük orijinal dosyalar, pek çok varyant ve toplu içe aktarımlar genellikle bir kuyruğun içinde yer almalıdır.

Güvenilir bir sıralama şöyledir:

1. Orijinal yüklemeyi doğrula ve kaydet.
2. Bekleyen bir durum ile bir varlık kaydı oluştur.
3. Varlık kimliği veya depolama yolu ile bir işi yayınla.
4. İşin içinde kaynağı depolamadan yükle.
5. Gerekli her varyantı oluştur.
6. Tüm gerekli yazma işlemleri başarılı olduktan sonra varlığı hazır olarak işaretle.
7. Başarısızlıkları kaydet ve kontrollü yeniden denemelere izin ver.

Yeniden deneme işlemlerini idempotent tutun. Bir iş, aynı varyant yollarını üretmeli veya açık bir sürümleme politikası aracılığıyla bunları değiştirmelidir.

Üretim Kontrolleri

Kullanışlı façade, resim işleme etrafındaki operasyonel çalışmaları ortadan kaldırmaz:

• Kodlamadan önce MIME türünü, sıkıştırılmış boyutu ve piksel boyutlarını doğrulayın.
• Animasyonlu girişin izin verilip verilmediğine karar verin.
• Web sunucusu, PHP, işçi bellek ve işçi zaman aşımı sınırlarını belirleyin.
• Oluşturulan varyantların sayısını sınırlayın.
• Kabul edilen girdileri yeniden kodlamayı tercih edin; yüklenen bir dosyayı kamu türevi olarak saklamayın.
• Her depolama döner değerini kontrol edin, çünkü depolama yöntemleri string|false döner.
• İşleme süresini, başarısızlıkları ve işçi belleğini izleyin.
• Abone edilmiş orijinaller ve kısmi varyantları temizleyin.
• Her varlık varyantıyla birlikte nihai genişliği, yüksekliği, MIME türünü ve yolu saklayın.

Küçük bir sıkıştırılmış dosya, hafızada büyük bir bitmap’a genişleyebilir. Gerçek kaynak boyutları ve formatları ile sınırları test edin.

Mevcut Bir Uygulama Göç Etmeli mi?

Yeni API’nin anında bir yeniden yazmayı gerektirmediği unutulmamalıdır. Avatarlar veya ürün küçük resimleri gibi bir iş akışından başlayın ve eski ile yeni çıktıyı karşılaştırın:

• Kırpma ve ölçek davranışı
• EXIF yönü
• Çıktı boyutları
• MIME türü ve uzantısı
• Seçilen kalitedeki dosya boyutu
• Şeffaflık ve arka plan davranışı
• Destekleniyorsa animasyonlu giriş davranışı

Eğer uygulama, Laravel’in daha küçük API’sinin sunmadığı intervention işlemlerine bağımlıysa, o iş akışı için doğrudan Intervention kullanımını sürdürün. Dış bir resim CDN’si dinamik teslimat ve önbellekleme sağlıyorsa, Laravel’in yerel bileşeni otomatik olarak bunu değiştirmez.

Laravel 13.20, sıkı yolun daha tutarlı hale gelmesini sağlar. Girdi politikası, depolama tasarımı, kuyruklar, gözlem, ya da gerçekçi performans testleri gereksinimini ortadan kaldırmaz.

Tam Laravel 13.20 Image facade kılavuzu, yayımlanan her kaynak, dönüşüm, depolama yöntemi, çoklu varyant avatar denetleyicisi, duyarlı resim işaretleme, geçiş kılavuzu, testler ve v13.20.0 etiketiyle doğrulanan kesin uygulama detaylarını içermektedir.

Kaynaklar