Laravel Klasör Yapısı: app/ Dizinini Nasıl Düzenleriz (2026)

Seri: Her Laravel Projesinde Bulunması Gereken Yapı Taşları
Bölüm: 1 / 35 · Seviye: Başlangıç · Ön Gereksinimler: Giriş

Öğrenecekleriniz

• Neden varsayılan Laravel yapısı ~20 route’dan sonra bozuluyor
• Üretim uygulamalarında kullanılan klasör düzeni
• Her klasörde ne bulunmalı ve neden
• app/Support/ klasörünün uygulamanızın iç kütüphanesi olarak özel rolü
• Geliştiricilerin klasör yapısındaki yaygın hataları

Varsayılan Yapıyla İlgili Sorun

php artisan make:controller ProductController komutunu çalıştırdığınızda, Laravel tek bir app/Http/Controllers/ klasörü oluşturur. Bu, bir görev uygulaması için yeterlidir.

Ancak gerçek bir üretim uygulaması, 50’den fazla kontrolcü, 30’dan fazla servis, 20’den fazla iş ve 15’ten fazla model özelliği içerebilir. Her şey tek bir düz klasörde bulunduğunda, dosyaları aramak için kod yazmaktan daha fazla zaman harcarsınız.

En kötüsü: Her şey aynı yerde olduğunda, her şeyi aynı class içinde tutma arzusu doğar. Kontrolcüler kabarır. Modellerin mantığı büyür. Testler imkansız hale gelir.

Bu makaledeki yapı, doğru yeri belirtmekle iyi alışkanlıklar kazanmanızı sağlar.

Tam Klasör Düzeni

İşte bu serideki projelerde kullanılan tam app/ yapısı.

app/
├── Actions/
│   └── Order/
│       ├── CreateOrderAction.php
│       └── CancelOrderAction.php
│
├── Console/
│   └── Commands/
│       ├── HeartbeatCommand.php
│       └── PruneOldLogsCommand.php
│
├── DTOs/
│   ├── OrderCustomerData.php
│   └── ServiceCheckResult.php
│
├── Enums/
│   ├── CacheKeys.php
│   ├── PaymentStatus.php
│   └── ServiceStatus.php
│
├── Events/
│   └── OrderPlaced.php
│
├── Exceptions/
│   └── InsufficientStockException.php
│
├── Exports/
│   ├── BaseExport.php
│   └── OrdersExport.php
│
├── Http/
│   ├── Controllers/
│   │   ├── Admin/
│   │   │   └── DashboardController.php
│   │   └── Api/
│   │       └── V1/
│   │           └── OrderController.php
│   ├── Middleware/
│   │   ├── RequestLogger.php
│   │   └── SecureHeadersMiddleware.php
│   └── Requests/
│       ├── StoreOrderRequest.php
│       └── UpdateOrderRequest.php
│
├── Jobs/
│   ├── HeartBeat.php
│   └── ProcessPaymentJob.php
│
├── Listeners/
│   └── SendOrderConfirmation.php
│
├── Mail/
│   ├── ExceptionOccurred.php
│   └── OrderConfirmationMail.php
│
├── Models/
│   ├── Order.php
│   └── User.php
│
├── Notifications/
│   └── OrderShippedNotification.php
│
├── Observers/
│   └── OrderObserver.php
│
├── Policies/
│   └── OrderPolicy.php
│
├── Providers/
│   └── AppServiceProvider.php
│
├── Rules/
│   └── ValidCouponCode.php
│
├── Services/
│   ├── Core/
│   │   └── ErrorReporter.php
│   ├── Status/
│   │   ├── StatusService.php
│   │   ├── Contracts/
│   │   │   └── StatusServiceInterface.php
│   │   └── Checks/
│   │       ├── DatabaseCheck.php
│   │       └── CacheCheck.php
│   └── Order/
│       ├── OrderService.php
│       └── OrderPaymentService.php
│
└── Support/
    ├── Contracts/
    │   └── IsSluggable.php
    ├── Traits/
    │   ├── Console/
    │   │   └── LogsCommandMessages.php
    │   ├── ModelChangeLogger.php
    │   ├── Sluggable.php
    │   └── InteractsWithMedia.php
    └── File.php

Klasör Klasör Analizi

app/Actions/

Burası için: Tek amaçlı sınıflar, belirli bir işlemi gerçekleştirmek için.

Bir Action, bir Servisten farklıdır. Bir Servis, enjekte edip birden fazla kez çağırdığınız bir işbirlikçidir. Bir Action, bir kez yürütülerek bir atomik işlemi tamamlar.

// app/Actions/Order/CreateOrderAction.php
final readonly class CreateOrderAction
{
    public function __construct(
        private HostingPlanPricingService $pricingService
    ) {}

    public function execute(User $user, OrderCustomerData $data, Collection $cartItems): Order
    {
        return DB::transaction(function () use ($user, $data, $cartItems): Order {
            $order = Order::create([...]);
            $this->attachOrderItems($order, $cartItems);
            return $order;
        });
    }
}

Bir alana ait 3’ten fazla işlem varsa, alt klasörlerde gruplandırılmalıdır: Actions/Order/, Actions/ServiceRequest/, Actions/Certificate/.

app/DTOs/

Burası için: Değişmez veri transfer nesneleri – katmanlar arasında veri taşımak için tipli konteynerler.

DTO’lar, ham dizileri değiştirir. $data['first_name'] yerine, tipli özelliklere sahip bir OrderCustomerData nesnesi geçirirsiniz.

// app/DTOs/OrderCustomerData.php
final readonly class OrderCustomerData
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public string $email,
        public PaymentGateway $paymentGateway,
        public ?string $address = null,
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            firstName: (string) ($data['first_name'] ?? ''),
            lastName: (string) ($data['last_name'] ?? ''),
            email: (string) ($data['email'] ?? ''),
            paymentGateway: PaymentGateway::tryFrom($data['payment_gateway'] ?? '') ?? PaymentGateway::Unknown,
        );
    }
}

readonly belirteci (PHP 8.1+) nesnelerin yapım aşamasından sonra değiştirilmesini engeller – bu, taşıdığınız veriler için mükemmeldir.

app/Enums/

Burası için: Sabit bir değer setini temsil eden türlendirilmiş sabitler.

Enums, 'status' => 'pending' gibi sihirli dizeleri değiştirir. IDE tamamlama, statik analiz tip kontrolü sunar ve değerlere davranış ekleme yeteneği sağlar.

// app/Enums/CacheKeys.php
enum CacheKeys: string
{
    case DashboardOrders = 'admin.dashboard.orders';
    case DashboardClaims = 'admin.dashboard.claims';

    public function forYear(int $year): string
    {
        return sprintf('%s.%d', $this->value, $year);
    }
}

// Kullanım
Cache::flexible(CacheKeys::DashboardOrders->value, [1800, 3600], fn () => ...);
Cache::flexible(CacheKeys::DashboardOrders->forYear(2024), [1800, 3600], fn () => ...);

app/Services/

Burası için: Tek bir Action içinde yer almayan statik alan mantıkları – sorgulamalar, hesaplamalar, koordinasyon veya harici API’lerle entegrasyonlar.

Servislerinizi alanlarına göre alt klasörlerde düzenleyin: Services/Order/, Services/Status/, Services/Core/. Services/Core/ klasörü özeldir – tüm uygulamayı kapsayan altyapı servislerini, örneğin ErrorReporter, barındırır.

Servisler, sözleşmelere (arayüzlere) sahip olabilir. Sahip olduklarında, arayüzü AppServiceProvider içinde uygulamaya bağlayın.

// app/Services/Order/OrderService.php
final class OrderService
{
    public function __construct(
        private readonly StripePaymentServiceInterface $stripe,
    ) {}

    public function processPayment(Order $order, string $paymentIntentId): void
    {
        // Stripe ile sipariş arasındaki koordinasyonu sağla
    }
}

app/Support/

Burası için: Uygulamanın birçok yerinde kullanılan ortak yardımcılar, tekrar kullanılabilir özellikler ve sözleşmeler.

Burası, çoğu geliştiricinin atladığı en önemli klasördür. app/Support/ klasörünü, uygulamanızın içinde yaşayan özel bir paket olarak düşünün. Bir dizi alanla ilgili olmayan ama birçok kişi tarafından kullanılan şeyleri buraya koymalısınız.

app/Support/
├── Contracts/            # Davranışı tanımlayan arayüzler
│   └── IsSluggable.php
├── Traits/
│   ├── Console/
│   │   └── LogsCommandMessages.php  # Hem konsol hem log çıktıları
│   ├── ModelChangeLogger.php         # Her model için denetim izi
│   ├── Sluggable.php                 # URL sluglarını otomatik olarak oluşturur
│   ├── HasAddress.php                # Adres alanları karışımı
│   └── InteractsWithMedia.php        # Medya yükleme/alım
└── File.php                          # Dosya yardımcı: hash, MIME, güvenli isimler

Temel fark: Support/, altyapı ve çapraz kesim endişeleri içindir. Eğer aynı özelliği ikinci bir model için yazıyorsanız, onu Support/Traits/ içine taşıyın.

app/Http/Controllers/

Burası için: HTTP işleyicileri – başka bir şey değil.

Bir kontrolcünün görevi: bir isteği almak → doğrulamak → yetkilendirmek → bir servis veya eyleme devretmek → bir yanıt döndürmek. Hepsi bu. İş mantığı, veritabanı sorguları veya döngüler yoktur.

Kontrolcüleri, roller veya alanlar tarafından alt klasörlerde gruplandırın: Controllers/Admin/, Controllers/Api/V1/, Controllers/Domain/.

app/Http/Requests/

Burası için: Hem doğrulama (rules()) hem de yetkilendirme (authorize()) işlemlerini yönleten Form Requests.

Her form gönderimi veya API yazma işlemi için bir Form Request olmalıdır. Bunları kontrolcülere göre gruplandırın.

app/Observers/

Burası için: Model yaşam döngüsü olayları (oluşturulan, güncellenen, silinen vb.) için Eloquent olay kancaları; yan etkileri tetiklemek için.

Observers, model boot yönteminde mantık koymaktan daha iyidir çünkü ayrı bir class içindedirler, test edilebilirler ve model dosyanızı aşırı büyütmezler.

app/Policies/

Burası için: Yetkilendirme mantığı — kimin, hangi kaynağa ne yapmasına izin verilir.

Bir kullanıcı tarafından işlem yapılabilen her Model’in bir Politicsi olmalıdır. Politikaları AppServiceProvider içinde kayıt ettirin veya Laravel’in otomatik keşfine bırakın.

Kaçınılması Gereken Yaygın Hatalar

Hata 1: Her şeyi tek bir düz klasörde tutmak. Controllers/ProductController.php, Controllers/UserController.php, Controllers/AdminDashboardController.php — hepsi bir klasörde, 40 dosya. Alt klasörleri kullanın.

Hata 2: app/Support/ klasörünü atlamak. Üç modelde aynı özelliğe ihtiyacınız olduğunda, onu kopyalar ve yapıştırırsınız. Sonra bir kopyadaki hatayı düzeltir ve diğer ikisini unutursunuz. Bu nedenle Support/Traits/ dizini vardır.

Hata 3: app/Helpers/ klasörünü bir toplama alanı olarak kullanmak. 50 fonksiyon içeren bir helpers.php dosyası, bir tanrı dosyasıdır. Her fonksiyon, ilgili sınıf içinde bir yöntem veya uygun bir destek sınıfında statik bir yöntem olmalıdır.

Hata 4: Servisleri alanlarına göre gruplandırmamak. Services/CreateUserService.php, Services/UpdateUserService.php, Services/DeleteUserService.php — bir alan için üç dosya. Services/User/ olarak bir alt klasör kullanın.

Ana Çıkarımlar

• Klasör yapısı iyi alışkanlıkları zorlar. Kod için doğru yerlerin olduğu yerde, yanlış yere koyma olasılığınız daha düşüktür.
• app/Support/ içsel kütüphanenizdir. Kodları, birbirine bağlamadan alanlar arasında paylaşmak için kullanın.
• Her klasörde 3–4 ile ilgili dosyanız olduğunda alanlara göre gruplandırın.
• Kontrolcüler, yalnızca HTTP’yi işleyen Http/Controllers/ içinde yer almalıdır. Sorumluluklarını aştıklarında genişlemelerine izin vermeyin.

İpuçları ve Dikkat Edilecek Hususlar

⚠️ Uyarı: İlk özelliğinizden önce yapıyı aşırı mühendislik etmeyin. Yukarıdaki düzenle başlayın, büyüdükçe hareket ettirin. Prematüre alan ayrımı, boş klasörler ve garip ithalatlarla sonuçlanır.

💡 İpucu: Bir sınıfın nereye ait olduğundan emin değilseniz — “Bu HTTP ile alakalı mı?” → Http/. “Tek bir görev mi?” → Actions/. “Birden fazla modeli kapsıyor mu?” → Services/. “Paylaşılan yardımcı mı?” → Support/.

🔥 Uzman Notu: app/Support/, içsel lib/ klasörünüzdür. Her şeyin bağımlı olduğu, fakat hiçbir alanı sahiplenmeyen bir kod parçasıdır. Dönüşümlü bağımlılıkları önlemek için ayrı tutun.

Daha Fazla Okuma

← Giriş | Sonraki: Yapılandırma Stratejisi →