Laravel DTO’ları Uygulamada: Tipli Girdi Nesneleri ile Daha Temiz Kontrolcüler

Lararvel’deki Controllers genellikle input handling nedeniyle büyür. Bir proje büyüdüğünde, sıklıkla tekrar eden doğrulama dizileri, ad-hoc input dönüşümleri (örneğin, kesme veya tür değiştirme) ve web ile API endpointleri arasında tutarsız alan adlandırmaları ile karşılaşırsınız.

Başlangıçta, doğrulamayı controller içinde yapar, modeli oluşturur ve bir yanıt döndürürsünüz.

Sonra proje büyüdüğünde, alanlar değişir, JSON API eklenir, bir admin panel eklenir… ve aniden şunlarla karşılaşırsınız:

• birden fazla endpointte tekrar eden doğrulama dizileri,
• ad-hoc input dönüşümleri (trim, casts, varsayılan değerler),
• web ve API arasında tutarsız alan adlandırmaları/haritalama,
• ve mini hizmetler gibi görünen controllerlar.

Bu problemi çözmek için etkili bir desen, DTO (Data Transfer Object) tanıtmak: endpointinizin kabul ettiği sözleşmeyi temsil eden tiplenmiş bir nesne.

Bu yazıda DTO’ların ne olduğunu, neden önemli olduklarını ve Laravel’de nasıl temiz bir şekilde uygulanacağını inceliyoruz.

DTO nedir (Laravel bağlamında)?

DTO, katmanlar arasında veri taşıyan basit, tiplenmiş bir nesnedir. Laravel bağlamında, belirli bir eylem için uygulamanızın ne beklediğini tanımlayan bir input sözleşmesi olarak düşünebilirsiniz.

Laravel’de DTO’ları input nesneleri olarak kullanmayı seviyorum:

• kabul edilen alanların net listesi,
• tiplenmiş özellikler (string, int, bool…),
• veri şekli yanında doğrulama kuralları,
• isteğe bağlı normalizasyon (trim, casting, varsayılanlar).

Şöyle düşünün:

“Uygulamamın bu eylem için beklediği tam input budur.”

Neden standart doğrulama her zaman ölçeklenmez?

request()->validate() küçük uygulamalar için harika, ancak büyüdükçe birkaç sorun ortaya çıkar:

• Yinelenme: Endpointler genellikle aynı kuralları kopyalayıp yapıştırır.
• Gizli Şekil: Diziler, bir nesnenin yaptığı kadar iyi bir şekilde input yapısını belgelemez.
• Her yerde Dönüşüm: trim(), intval() veya varsayılan değerler, birden fazla controllerda dağılır.
• Refaktör Fikir Kaybı: Bir alan adını değiştirmek, dizilerdeki dizeleri düzeltmek için birçok dosyada avlanmak anlamına gelir.

Ne kadar çok endpointiniz olursa, “input handling” tutarsızlıkların ana kaynağı olur.

DTO Kullanmanın Pratik Kazançları

1. Net Input Sözleşmesi: Tek bir sınıfa bakarak alanları, türleri ve kuralları hemen görebilirsiniz.
2. Merkezi Normalizasyon: DTO’lar, metinleri kesmek, boolean değerleri dönüştürmek veya eski anahtarları haritalamak (örneğin, full_name → name) için tek bir alan sağlar.
3. Daha İnce Controllers: Controllerlar, iş kurallarını kodlamak yerine isteği yönlendirmek için orijinal amacına geri döner.

Somut bir örnek (önce / sonra)

Bir “rezervasyon” endpointi hayal edelim.

ÖNCE: doğrulama + haritalama controller içinde

// app/Http/Controllers/ReservationController.php

public function store()
{
    $data = request()->validate([
        'name'   => [,,],
        => [,],
        => [,,,],
    ]);

    Reservation::create($data);

    return back();
}

Bu çalışıyor. Ancak zamanla sıklıkla ekleyeceksiniz:

• name kesme,
• varsayılan değerler,
• API’ye özel haritalama,
• başka bir endpointte tekrar eden kurallar.

SONRA: bir DTO, şekil + doğrulamayı merkezileştirir

Laravel’de popüler bir yaklaşım Spatie Laravel Data‘dır.

// app/Data/ReservationData.php

use Spatie\LaravelData\Data;

final class ReservationData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public int $guests,
    ) {}

    public static function rules(): array
    {
        return [
            => [,,],
            => [,],
            => [,,,],
        ];
    }
}

Artık controller temiz bir yönlendirici haline gelir:

// app/Http/Controllers/ReservationController.php

final class ReservationController
{
    public function store(ReservationData $data) // otomatik olarak doldurulmuş + doğrulanmış
    {
        Reservation::create($data->all());

        return back();
    }
}

Ne değişti?

• Şekil açık ve tiplenmiş.
• Doğrulama merkezileştirildi.
• Controller, eyleme odaklandı.

Normalleşme nerede yer alır?

İleride girdileri normalleştirme ihtiyacı duyacaksınız.

Örnekler:

• metinlerde kesme,
• boolean değerleri dönüştürme,
• guests değerini "3"‘ten 3‘e dönüştürme,
• eski bir anahtarı haritalama (full_name → name).

DTO’larla normalizasyon, belirli bir yerde (kullanacağınız kütüphaneye/şemaya bağlı) gerçekleşebilir. Burada önemli olan, tam olarak hangi yöntem adının kullanıldığı değil, bunun için tek bir alanın olmasıdır.

DTO’lar, Form Requests ve Politikalara karşı (nasıl bir araya gelirler?)

Temiz bir zihinsel model:

• Politikalar → kaynak düzeyinde yetkilendirme (“BU projeyi güncelleyebilir miyim?”)
• Form Request’lar → bir eylem için isteği doğrulama (harika bir varsayılan yaklaşım)
• DTO’lar → alan/hizmet katmanınız tarafından kullanılan tiplenmiş input sözleşmesi

Birçok gerçek uygulamada, karışım iyi çalışır:

• Eylem düzeyinde doğrulama/yetkilendirme için bir Form Request kullanın,
• Doğrulanmış verilerden bir DTO oluşturun,
• DTO’yu bir hizmet/kullanım durumu için geçirin.

Hedef aynı: controller’ı ince tutmak ve kuralları tutarlı hale getirmek.

Basit bir benimseme stratejisi

Projeniz zaten mevcutsa, her şeyi bir anda refaktör etmek zorunda değilsiniz.

Şunlardan başlayın:

1. Sıklıkla değişen bir endpoint (genellikle store veya update).
2. Input’ları için bir DTO çıkarın.
3. Controller’ların $data->all() (veya eşdeğeri) kullanmasını sağlayın.
4. Kritik doğrulama için birkaç test ekleyin.

Hızlı kontrol listesi

• [ ] Girdilerin net bir “sözleşmesi” var mı (DTO veya Form Request)
• [ ] Doğrulama, endpointler arasında tekrarlanmıyor mu
• [ ] Controller’lar yönlendiriyor, iş kurallarını kodlamıyor mu
• [ ] Normalizasyon (trim/casts/defaults) için tek bir alan var mı
• [ ] Yetkilendirme Politikalardan (veya en azından merkezi bir yerden) mi yapılıyor

Sonuç

DTO’lar Laravel’de “zorunlu” değildir, ancak uygulamanız büyüdüğünde harika bir araçtır:

• azaltılmış tekrar,
• daha az tutarsızlık,
• net input sözleşmeleri,
• daha küçük controllerlar,
• güvenli refaktörler.

Controller’larınızın mini hizmetlere dönüşmüş olduğunu hissettiyseniz, DTO’lar yapıyı geri kazanmak için basit bir modeldir.

Referanslar

• Spatie Laravel Data belgeleri (istek → veri nesnesi, doğrulama vb.)