Laravel 13.15’teki Yenilikler: Tiplenmiş Çeviriler ve Daha Fazla

İlk olarak hafiz.dev‘de yayımlandı

Çoğu sürüm güncellemesi hızlıca geçiştirilebilir, ancak Laravel 13.15’te hemen güncellemek için bir sebep var: date_equals doğrulama kuralındaki ciddi bir güvenlik açığı. Eğer tarihleri kimlik doğrulama, planlama veya erişim pencereleri gibi kritik alanlarda doğruluyorsanız, bu değişiklik önemli. Diğer üç önemli değişiklik (typted çeviri erişimleri, JSON Schema birleşimleri ve özel bir Cloud kuyruk sürücüsü) ise yaşam kalitesini artırıyor ama uyku kaçıracak kadar önemli değil. İşte her birinin ne yaptığına dair kısa bir bilgi.

Bir not: Laravel her hafta küçük sürümler yayınlıyor, bu yüzden bunu okuduğunuzda 13.16’dan 13.19’a kadar olan sürümler de çıkmış olabilir (13.19, HTTP sorgu yöntemi desteği ekledi). Ancak mevcut 13.15 özelliklerini değiştirmez ve bu küçük sürümler geriye dönük uyumlu olduğundan, composer update ile her şeyi anında alırsınız.

Önemli Güvenlik Düzeltmesi

Buradan başlayalım çünkü bunun gerçekten bir etkisi var.

date_equals doğrulama kuralı arka planda gevşek karşılaştırma kullanıyordu. Bu masum görünse de, kötü bir tarih dizesinin nasıl işlendiğini izlerseniz, durum değişiyor. Geçersiz bir tarih null olarak tanımlanıyor ve PHP’de null == 0 ifadesi true olarak değerlendiriliyor. Eğer referans tarihiniz geçersiz bir tarih dizesi ile karşılaşırsa, date_equals doğrulamasını geçebilir.

Şöyle bir kural düşünün:

$request->validate([
            'event_date' => 'required|date_equals:' . $referenceDate,
        ]);

Eğer $referenceDate geçersiz bir zaman damgası ile sonuçlanırsa ve bir saldırgan geçersiz bir tarih gönderirse, bu sıkı karşılaştırma ile geçilebilir. Bu, bir doğrulama atlamasıdır ve doğrulama atlamaları, biri baktığında ortaya çıkan sessiz hatalardır.

Düzeltme, eşitlik kontrolünü sıkı kıyaslama ile yaparak geri dönük kıyaslama ile gerçek DateTime nesneleri için çalışmaya devam ediyor, bu nedenle kodunuzda değişiklik yapmanıza gerek yok. Framework’ü güncelliyorsunuz ve açığı kapatıyorsunuz. İşte bu yüzden bu sürüm öne çıkıyor.

Aynı sürüm ayrıca yönlendirme unserialize işlemine de sıkı bir kontrol ekledi; bu da yönlendirme önbellekleme ve çözümleme sırasında hangi sınıfların kabul edileceğini kısıtladı. Bu, tarih açığına göre daha küçük bir alan ama route:cache esnasında nesne enjekte etme taktikleri için daha az kapsam sağlıyor. Bu güncellemeyi mümkün olan en kısa sürede yapmak için başka bir sebep.

Typed Çeviri Erişimleri

Bu, başlı başına bir özellik ve sıkı statik analiz yapan herkes için hoş bir gelişme.

Laravel’in çeviri yardımcıları her zaman geniş türler döndürüyordu. __() fonksiyonu array|string|null dönerken, trans() ise Translator|array|string döner. Bu, bir Blade şablonunda sadece bir diziyi ekrana yazdırıyorsanız kabul edilebilir. Ancak başka bir yerde, bir yöntemin string döndürmesi gereken bir durumda __('some.key') kullanıldığında PHPStan veya Psalm bunun array veya null döndürebileceği için sorun çıkarıyordu.

13.15, Translator üzerinde iki typed erişim noktası ekliyor:

public function label(): string
{
    return trans()->string($this->name);
}

public function options(): array
{
    return trans()->array($this->options_key);
}

trans()->string() bir string döndürmeyi garanti ederken, trans()->array() bir dizi döndürmeyi garanti eder. Bu, config() ve request() üzerinde mevcut olan typed erişim noktalarına zıt bir model oluşturuyor. Yani eğer config()->string('app.name') kullandıysanız, bu hemen tanıdık gelecektir.

AI Yapılandırılmış Çıktı İçin JSON Schema Birleşimleri

Bu özellik daha dar ama Laravel AI SDK ile çalışırken önemli.

JsonSchema bileşeni iki ilgili yetenek kazandı. İlk olarak, ham JSON Schema dizisini Type nesnelerine geri döndüren fromArray() ayrıştırıcısı, bu daha önce yapılan serileştirme işleminin tersidir. İkincisi ve günlük kullanımda daha faydalı olan ise, schema yapıcı artık anyOf ile çoklu tür birleşimlerini destekliyor.

Neden anyOf önemlidir? Yapılandırılmış çıktı, bir modelin belirli bir şemaya uygun JSON döndürmesini zorlar. Bazen bir alan birden fazla şekil alabilir. Bir destek ticket’ının resolution alanı, basit bir not olduğunda bir string olabilir, ya da yapılandırılmış bir yükseltme olduğunda bir nesne olabilir. anyOf öncesinde, “bu alan bu belirgin şemalardan biri” şeklinde ifadeyi temiz bir şekilde ifade edemezdiniz. Artık edebilirsiniz ve hem OpenAI hem de Gemini anyOf‘u yapılandırılmış çıktı API’lerinde desteklediği için, bu sağlayıcıya doğrudan geçer.

Birden fazla türde yanıtlar döndürüyorsanız, bu, ifadelerinizi genişletir ve bir string alanına geri dönmeden kendi kendine çözümleme yapmanızı sağlar. Eğer hala AI SDK ile uğraşmadıysanız, bu ayrıntıyı kaydedin fakat hemen harekete geçmeyin.

Özel Bir Cloud Kuyruk Sürücüsü

Laravel Cloud’da dağıtım yapıyorsanız ve yönetilen kuyruklarını kullanıyorsanız, 13.15’teki birçok değişiklik birinci sınıf kuyruk sürücüsü oluşturuyor.

Pratik farklılıklar: yönetilen kuyruklar artık hizmet sağlayıcılardan önce başlıyor, bu sayede kuyruk bağlantısı yaşam döngüsünün daha erken bir aşamasında hazır oluyor. Eksik yapılandırılmış bir kuyruk, belirsiz bir şekilde başarısız olmaktansa net bir ManagedQueueNotFoundException hatası veriyor. FIFO kuyruk isimlendirme normallaştırması düzeltildi. Ayrıca, istek ID başlığı X-Request-ID‘den Cloud-Request-ID‘ye değişti ve bu artık günlüklerinize yansıyor. Bu, üretimde bir kuyruğa alınmış iş üzerinden bir isteği izlerken faydalı olabilir.

Bir diğer küçük iyilik ise Queue::route()‘un hem kuyruk ismi hem de bağlantısı için enum durumlarını kabul etmesidir. Kuyruk isimlerinizi magic string’leri önlemek için yedek bir enum içine taşıdıysanız, her yerde ->value çağırmak yerine enum’u doğrudan geçebilirsiniz.

Eğer Laravel Cloud üzerinde değilseniz, bu değişiklikler sizi etkilemeyecek. Ama eğer kullanıyorsanız, bu, en az sürprizlerin olduğu kısım için sessiz bir güvenilirlik yükseltmesidir. Daha geniş kuyruk yapısıyla ilgili bilgiler için kuyruk işleri kılavuzuna ve yönetilen kuyruklar ve Horizon karşılaştırmasına göz atmanızı öneririm.

Bilinmesi Gereken Küçük Düzeltmeler

Yayınlanacak bir sürümde dikkat çekmeyen ancak birinin bir gününü kurtaracak birkaç değişiklik:

Number yardımcı sınıfı üç kenar durumu düzeltildi. Number::fileSize() artık geçersiz byte değerlerini utandırmadan işleyebiliyor. Number::trim() artık INF ve NAN için null döndürmüyor ve Number::pairs() negatif adım değerlerini işleyip sıfır adımda net bir hata fırlatıyor. Eğer kullanıcıdan elde edilen sayıları bu fonksiyonlara geçmişseniz, bu sıkılaştırmalar hoş karşılanacaktır.

İki sonsuz döngü hatası ortadan kaldırıldı: biri bir model kapsamı özel bir özellik kullanılarak tanımlandığında, diğeri bir middleware grubunun kendisini referans göstermesi durumunda. Bu tür hatalar büyük uygulamalarda kolayca yapılabilir ve debug edilmesi zordur, bu nedenle framework’ün bu tür durumda hata veriyor olması önemli bir geliştirme.

Bir diğer küçük operasyonel kazanım: queue:failed artık başarısız işleri belirtmek için gerçek sınıf ismini gösteriyor. Bu, başarısız bir kuyruğun kontrolünü çok daha hızlı hale getiriyor. Tüm kuyruk ve Artisan komutlarının tam listesine Laravel Artisan Komutları referansına bakarak ulaşabilirsiniz.

Güncelleme Yapmalı Mısınız?

Evet, özellikle de tarih doğrulama kuralındaki date_equals güvenlik düzeltmesi için. Bu bir “belki güncelleriz” durumu değil, kapatılan bir güvenlik açığı ve güncelleme geriye dönük uyumlu composer update ile yapılabilir, kod değişikliği gerektirmez.

Geri kalan da yolda bonus olarak kazanacağınız avantajlar. Typed çeviri erişimleri, sıkı tipli kodu temizliyor, anyOf AI yapılandırılmış çıktı ile modelleme yelpazenizi genişletiyor ve Cloud kuyruk sürücüsü yönetilen kuyrukları daha öngörülebilir hale getiriyor. Hiçbiri hiçbir şeyi bozmaz çünkü bunlar küçük sürümlerdir ve Laravel bu tür sürümlerde kırıcı değişiklikler yapmaz.

Eğer birkaç küçük sürümün gerisindeyseniz, güncelleme aynı zamanda 13.16’dan güncelliğe kadar her şeyi de dahil edecektir. Bu yüzden, buradakiler dışında uygulamanız için ilgili olan bir şey varsa değişim günlüğünü kontrol etmenizde fayda var. Eğer tamamen eski bir ana sürüm üzerindeyseniz, Laravel 12’den 13’e geçiş kılavuzu bu sıçramayı ele alır.

Sıkça Sorulan Sorular

date_equals güvenlik düzeltmesini almak için herhangi bir kod değişikliği yapmam gerekiyor mu?

Hayır. Düzeltme tamamen framework’ün doğrulama mantığının içinde yer alıyor. composer update komutunu çalıştırarak Laravel 13.15 veya daha üst sürümlere güncelleyerek güvenlik açığını kapatıyorsunuz. Gerçek DateTime karşılaştırmaları da eski şekilde çalışmaya devam ediyor.

trans()->string() ile __() arasındaki fark nedir?

__() array|string|null döndürür, bu da sıkı tipli kodda dönüşüm veya doğrulama ihtiyacı doğurur. trans()->string() string döndürme türünü garanti ederken, trans()->array() ise dizi döndürmeyi garanti eder. Bunlar, tipli yöntem gövdesi ve statik analiz için kullanılır, Blade’de __()‘a karşılık gelmez.

JSON Schema anyOf desteği tüm AI sağlayıcıları ile çalışır mı?

anyOf desteği Laravel’in şema yapıcısında mevcut ve hem OpenAI hem de Gemini anyOf‘yu yapılandırılmış çıktı API’lerinde kabul ediyor, bu nedenle bu sağlayıcılara geçiş yapar. Diğer sağlayıcıların desteklenmesi, yapılandırılmış çıktı API’lerinin birleşimleri kabul edip etmediğine bağlıdır.

Cloud kuyruk sürücüsü, Laravel Cloud’u kullanmıyorsam işe yarar mı?

Hayır. Bu değişiklikler Laravel Cloud’un yönetilen kuyrukları için özel olarak hedeflenmiştir. Redis, SQS veya bir veritabanı sürücüsü ile kendi kuyruk altyapınızı çalıştırıyorsanız, bunlar geçerli değildir. Ancak Queue::route()‘un enum’ları kabul etmesi genel bir geliştirme olup herkes için geçerlidir.

Laravel 13.15 en son sürüm mü?

Muhtemelen okuduğunuzda değil. Laravel, yaklaşık olarak her hafta küçük sürümler çıkarıyor, bu yüzden 13.16 ve sonrası çoktan çıkmış olabilir. Küçük sürümler geriye dönük uyumlu olduğundan, güncelleme ile 13.15’in özelliklerini yanı sıra daha yenilerini de almış olursunuz.

Sonuç

Laravel 13.15 çoğunlukla sessiz bir sürüm ve bu da iyi. Her sürümün büyük bir özelliğe sahip olması gerekmez. Typed çeviri erişimleri, hayat kalitesinde küçük bir kazanç sağlarken, anyOf desteği AI SDK’nın yeteneklerini genişletiyor ve Cloud kuyruk sürücüsü yönetilen kuyrukları daha öngörülebilir hale getiriyor.

Ama date_equals düzeltmesi, takviminizi değiştirecek olan bir durum. Bunun için güncelleyin, diğer özellikleri bonus olarak kazanın ve ilerleyin.