Çoğu Laravel Projesinin Başarısız Olma Nedenleri ve Çözüm Yolları

Seri: Her Laravel Projesinde Bulunması Gereken Yapı Taşları
Bölüm: Giriş · Seviye: Yeni başlayanlar — ön koşul yok

Konuşulmayan Sorun

Laravel eğitimini tamamladınız. İlk gerçek projenizi oluşturdunuz. Her şey çalışıyor. Yayınlıyorsunuz.

Altı ay sonra yeni bir özellik eklemeye karar veriyorsunuz ve tek bir değişiklik yapmak için beş farklı dosyayı açmanız gerektiğini fark ediyorsunuz. Kontrolörleriniz 300 satır uzunluğunda. Modelleriniz çok fazla bilgiye sahip. Yazdığınız testler, metot adını değiştirdiğiniz için çalışmıyor. Kod tabanını açmak için korkuyor olabilirsiniz.

Bu bir beceri sorunu değil. Bu, bir mimari sorunu ve bu durum, yalnızca belgelerden Laravel öğrenen neredeyse herkesin başına gelebilir.

Laravel belgeleri, çerçevenin ne yapabileceğini göstermekte mükemmeldir. Ancak uygulamanız birkaç rotadan daha fazlasına büyüdüğünde nasıl organize edeceğinizi anlatmaz.

Bu seri bunu düzeltir.

Bu Seri Neleri Kapsıyor

35’ten fazla makalede, üretim Laravel uygulamalarında kullanılan kesin desenleri öğreneceksiniz — Laravel 8’den 12’ye kadar altı gerçek projeden çıkarılmıştır.

Bu teorik desenler değildir. Bu serideki her bir kod parçası, gerçek işlemleri işleyen, gerçek kullanıcılarla çalışan ve gerçek sunucularda çalışan uygulamalardan alınmıştır.

Konu başlıkları, her makalenin bir öncekine dayanarak düzenlenmiştir:

• Temel — klasör yapısı, yapılandırma, AppServiceProvider
• İstek yaşam döngüsü — ince kontrolörler, form istekleri, rota organizasyonu
• İş mantığı — hizmetler, eylemler, DTO’lar, model trait’leri, gözlemciler
• Arka plan işlemesi — işlerin, kuyrukların, HeartBeat deseni, Artisan komutları
• Olaylar ve bildirimler — alan olayları, e-posta, Slack kanalları
• Gözlemlenebilirlik — istek günlükleme, hata raporlama, yavaş sorgu tespiti, denetim izleri
• Önbellekleme — tipli önbellek anahtarları, esnek önbellekleme
• Geliştirici deneyimi — composer betikleri, git kancaları, CI/CD süreçleri
• Kod kalitesi — Larastan, Rector, Pint, test stratejisi
• Gelişimde AI — AI araçları, kod asistanları ve otomasyonların iş akışında kullanımı
• Kayıp parçalar — durum sayfaları, DTO’lar, API kaynakları, hız sınırlaması, medya yönetimi

Ulaşacağınız Mimari

Bu serinin sonunda, app/ klasörünüz aşağıdaki gibi görünecek:

app/
├── Actions/          # Tek amaçlı yürütücüler (CreateOrder, RejectRequest)
├── Console/
│   └── Commands/     # LogsCommandMessages trait'ini kullanan Artisan komutları
├── DTOs/             # Katmanlar arasında değişmez veri taşıyıcıları
├── Enums/            # Tipli sabitler (CacheKeys, ServiceStatus, PaymentGateway)
├── Events/           # Önemli bir şey olduktan sonra ateşlenen alan olayları
├── Exceptions/       # Özel alan istisnaları
├── Exports/          # BaseExport hiyerarşisi aracılığıyla Excel/CSV dışa aktarma
├── Http/
│   ├── Controllers/  # İnce: doğrula → yetkilendir → devret → yanıtla
│   ├── Middleware/   # RequestLogger, SecureHeaders, RoleMiddleware
│   └── Requests/     # authorize() ve rules() içeren Form İstekleri
├── Jobs/             # HeartBeat dahil kuyruklu işler
├── Listeners/        # Olay dinleyicileri (genellikle kuyruklu)
├── Mail/             # ExceptionOccurred dahil mailables
├── Models/           # Eloquent modeller, trait zenginleştirilmiş
├── Notifications/    # Çok kanallı bildirimler
├── Observers/        # Model yaşam döngüsü için yan etkileri olan kancalar
├── Policies/         # Yetkilendirme mantığı, her kaynak için bir adet
├── Providers/        # AppServiceProvider ile konteyner bağlamaları ve makrolar
├── Rules/            # Özel doğrulama kuralı sınıfları
├── Services/
│   ├── Core/         # ErrorReporter ve diğer altyapı hizmetleri
│   ├── Status/       # Sağlık kontrolü hizmetleri
│   └── [Domain]/     # Alan gruplu durumdan bağımsız hizmetler
└── Support/
    ├── Contracts/    # Hizmetlerinizi uygulayan arayüzler
    ├── File.php      # Dosya yardımcıları
    └── Traits/       # Yeniden kullanılabilir mixin'ler (ModelChangeLogger, Sluggable, vb.)

Her klasörün bir nedeni var. Hiçbiri, sadece birinin bir blog gönderisi okuduğu için temiz görünmesi gerektiği için orada değil. Her desen, uygulamanız büyüdükçe karşılaşacağınız gerçek bir sorunu çözer.

Üç Kural

Bir sonraki kelimeyi okumadan önce, bunları görebileceğiniz bir yere yazın:

1. Değiştirme nedeni. Her sınıfın tam olarak bir değişiklik nedeni olmalıdır. Yeni bir özellik eklemek mevcut bir sınıfı değiştirmeyi gerektiriyorsa, muhtemelen yanlış sınırlar içindesiniz.

2. Mantığı aşağı it. Mantık, mantığı destekleyen en düşük katmanda yaşamalıdır. Bir şey Action olabiliyorsa, onu Service’e koymayın. Bir şey model kapsamına girebiliyorsa, onu kontrolörde barındırmayın.

3. Yanlış şeyi zorlaştır. Model::shouldBeStrict(), tipli özellikler, declare(strict_types=1) ve DB::prohibitDestructiveCommands() kullanın. Hataları tanıtmayı yapısal olarak zorlaştırın.

Bu Seri Neleri Varsayıyor

• Laravel’in temellerini biliyorsunuz (rotalar, modeller, kontrolörler, migrations)
• En az bir projenizi yayınladınız veya aktif olarak inşa ediyorsunuz
• PHP 8.1 veya sonrasını kullanıyorsunuz (çoğu örnek 8.3+ kullanıyor)
• Komut satırı ile rahatsınız

Tasarım desenleri, SOLID ilkeleri veya diğer teorik çerçeveler hakkında bilgi sahibi olmanıza gerek yok. Eğer biliyorsanız, buradaki desenleri tanıyacaksınız — ama her zaman neden‘i pratik terimlerle, soyut olmayan bir şekilde açıklayacağız.

Bu Seriyi Nasıl Okumalıyım

İlk önce makaleleri sırayla okuyun. Klasör yapısı makalesi, hizmetler makalesinden önce gelmelidir çünkü nelerin nerede olduğunu anlamadan neyi koyacağınızı öğrenemezsiniz.

Bütün seriyi okuduktan sonra referans olarak kullanın. Her makale, o belirli deseni uygularken tekrar okumak için yeterince bağımsızdır.

Kod örnekleri gerçektir. Doğrudan kopyalayabilirsiniz. İsimleri alanınıza göre değiştirin ve çalışacaktır.

Temel Çıkarsamalar

• Laravel’in belgeleri çerçevenin ne yaptığını gösterir — bu seri ise büyüdükçe nasıl organize edilir gösterecektir.
• Buradaki desenler, öğretici amaçlar için icat edilmemiş, gerçek üretim kod tabanlarından çıkarılmaktadır.
• Her şeyi yöneten üç kural vardır: kontrolörler yalnızca dört şey yapar, tüm durum tiplidir, her şey gözlemlenebilir.
• Seriyi ilk okuyuşunuzda sırayla okuyun; belirli desenleri uygularken bireysel makaleleri referans olarak kullanın.
• Her şeyi bir anda uygulamanıza gerek yok — ilk olarak en acil acınızı çözen deseni seçin.

Sıkça Sorulan Sorular

Başlangıçta bu desenlerin hepsini takip etmem gerekir mi? Hayır. Zaten hissettiğiniz bir acıyı çözen desenlerle başlayın. Eğer şişman kontrolörler sizi boğuyorsa, İnce Kontrolörler’i okuyun. Eğer testler sürekli kırılıyorsa, DTO’lar ve Eylem Sınıflarını okuyun. Seri, bağımlılığa göre sıralanmıştır, aciliyete değil.

Bu desenler küçük bir projede çalışır mı? Evet, daha az törenle. Küçük bir proje, Services/ altında altı alt dizine ihtiyaç duymaz — ancak ince kontrolörler, Form İstekleri ve klasör yapısı kurallarından fayda sağlar. İlkeleri uygulayın; karmaşıklığı projenizin boyutuna göre ayarlayın.

Karmaşık bir kod tabanım var. Nereden başlamalıyım? Öncelikle Klasör Yapısını okuyun, ardından İnce Kontrolörler — bu genellikle en büyük hızlı kazanımdır. Buradaki desenleri kullanarak bir seferde bir kontrolörü yeniden düzenleyin.

Bu desenler belirli bir Laravel sürümüne özgü mü? Desenler Laravel 10, 11 ve 12’de çalışır. Bazı özel durumlar (örneğin, bootstrap/app.php middleware kaydı) Laravel 11’de değişti, ancak her konu için makaleler, önemli olanlarda sürüm farklılıklarını not eder.

Bu desenler [Livewire / Filament / Inertia] ile çelişiyor mu? Hayır. Bu seri yalnızca arka uç katmanını kapsar — app/Actions/, app/Services/, app/DTOs/, vb. Bu klasörler ön uç çerçevenin altına yerleşir. Livewire bileşenleri, Filament kaynakları ve Inertia sayfaları, bu serinin tanımladığı aynı Eylemleri ve Hizmetleri çağırır.

İpuçları ve Dikkat Edilmesi Gerekenler

💡 İpucu: Her şeyi bir anda uygulamaya çalışmayın. Her sprintte bir desen seçin. Değer birikintisi — ince kontrolörleriniz olduğunda, eylem eklemek doğal hale gelir; eylemleriniz olduğunda, test etmek kolaylaşır.

⚠️ Uyarı: Bu desenler, 5 rotalı bir CRUD uygulamasında aşırı mühendislik gibi görünebilir. Bu sorun değil. 5 rotalı uygulama için ağır hisseden aynı desenler, 50 rotalı uygulamada hayati kurtarıcı görünür. Yargınızı kullanın, ancak onları çok erken reddetmeyin.

🔥 Uzman Notu: Mimari desenlerle ilgili en önemli şey, ne olduklarını bilmek değil — neden var olduklarını bilmektir. Bu serideki her makale, çözümden önce sorunu açıklar. Nedenini anladığınızda, deseni bağlamınıza uyarlayabilirsiniz, böylece sadece “kargo-kült” uygulamış olmazsınız.

İleri Okuma

Sonraki: Ölçeklenebilir Klasör Yapısı →