Modül Route Registry #

Starter kit, vendor-resident route gruplarını consumer uygulamalara mount etmek için modül route registry kullanır. İki senaryoyu ele alır: consumer'da henüz route dosyası olmayan temiz kurulumlar ve consumer'ın stub'ı override ettiği özelleştirilmiş kurulumlar.

Nasıl Çalışır #

StarterKitServiceProvider::moduleRouteRegistry() bir modül descriptor listesi döndürür. registerRoutes() bu listeyi dolaşır ve her modül için şu mantığı uygular:

1. Override kontrolü — overrideStubs listesindeki herhangi bir dosya consumer uygulamada (base_path(...)) mevcutsa, paket o modülü tamamen atlar. Consumer'ın route orchestrator'ı (routes/web.php veya routes/api.php) stub'ı yüklemekten sorumludur.
2. Otomatik mount — Override stub bulunamazsa paket, modülü tanımlı middleware katmanı altında Route::middleware(...)->group($loader) aracılığıyla mount eder.

Bu sayede hangi yol izlenirse izlensin bir modül asla iki kez kaydedilmez.

Modül Descriptor Yapısı #

Registry'deki her girişin dört alanı vardır:

[
    'name'          => 'file-manager',          // modül tanımlayıcısı (log/debug için)
    'overrideStubs' => [                        // mutlak yollar; herhangi biri eşleşirse → atla
        base_path('routes/web/file-manager-route.php'),
        base_path('routes/api/file-manager-route.php'),
    ],
    'middleware'    => ['web', 'auth', 'verified'], // otomatik mount yolu için dış grup
    'loader'        => static function (): void {   // vendor route dosyasını çağıran closure
        FileManager::routes();
    },
]

Registry, config/ içinde değil StarterKitServiceProvider içinde bulunur; çünkü loader bir closure'dır ve closure'lar config:cache tarafından serialize edilemez. Service provider metodu, her modülün middleware katmanı için tek kaynak-of-truth'tur.

Override Mekanizması #

Consumer kit'i kurduğunda sk:install stub route dosyalarını uygulamaya kopyalar:

• routes/web/file-manager-route.php
• routes/api/file-manager-route.php

Bu dosyalardan herhangi birinin varlığı, registry'ye consumer orchestrator'ının mount'u sahiplendiğini bildirir. Paket kenara çekilir ve modülü mount etmez.

Modülün Route'larını Özelleştirme #

Stub'ı kendi route dosyanızla değiştirin. Paket dosyayı algılar ve otomatik mount'u atlar. Dosyanız, o modülün route'larının kaydedileceği tek yer olur.

// routes/web/file-manager-route.php — consumer'a ait override
// Aşağıdaki tek satırı kendi grubunuz ve controller'ınızla değiştirin.

use Lvntr\StarterKit\Facades\FileManager;

FileManager::routes(); // vendor route'larını koruyun, ya da kaldırıp kendinizinkini yazın

Yalnızca vendor route'larını istiyorsanız dosyayı ince tutun — tek satırlık stub, paketin route dosyasına delege eder ve composer update aracılığıyla geleceğe dönük bir yükseltme yolu sağlar.

Override'ı Kaldırma (otomatik mount'a geri dönme) #

Stub dosyasını silin. Registry, bir sonraki istek boot'unda otomatik mount yoluna geri döner. Bu işlem güvenlidir — middleware katmanı, stub mevcutken orchestrator'ın uyguladığıyla aynıdır.

File Manager — Çalışan Örnek #

File manager, registry'deki tek vendor-resident modüldür. Descriptor'ı:

Loader, FileManager facade'ı aracılığıyla src/routes/file-manager.php'yi çağırır. Bu dosya, file-manager. isim öneki altında tam route grubunu tanımlar.

Share Endpoint Güvenliği (K1) #

Public share endpoint'i (GET /file-manager/share/{media}), route dosyasının içinde withoutMiddleware(['auth', 'verified', 'auth:sanctum', 'auth:api']) kullanır. Bu sayede endpoint, dışarıda hangi middleware grubu altında mount edilirse edilsin (otomatik mount yolu veya consumer stub'ı) — geçerli bir signed URL'e sahip kimliği doğrulanmamış kullanıcılar tarafından erişilebilir. Endpoint yalnızca doğrudan route üzerinde tanımlanan signed ve throttle:60,1 middleware'i ile korunur.

Yeni Vendor-Resident Modül Ekleme (Reçete) #

Bu reçete, route'larını consumer stub'larından vendor paketine taşıyan Faz 3 / Faz 6 modülleri için geçerlidir.

Adım 1. src/routes/<module-name>.php konumunda vendor route dosyasını oluşturun. Tüm route'ları bu dosyada tanımlayın. Burada dış auth middleware eklemeyin — dış katmanı registry yönetir.

Adım 2. Dosyayı require eden bir loader metodu veya facade metodu ekleyin, örneğin:

// src/Facades/MyModule.php
public static function routes(): void
{
    require __DIR__.'/../routes/my-module.php';
}

Adım 3. StarterKitServiceProvider içindeki moduleRouteRegistry()'ye bir descriptor ekleyin:

[
    'name'          => 'my-module',
    'overrideStubs' => [
        base_path('routes/web/my-module-route.php'),
    ],
    'middleware'    => ['web', 'auth', 'verified'],  // modül gereksinimlerine göre ayarlayın
    'loader'        => static function (): void {
        MyModule::routes();
    },
],

Adım 4. stubs/routes/web/my-module-route.php konumunda stub oluşturun — MyModule::routes()'u çağıran tek satırlık bir dosya. sk:install onu kurulumda consumer uygulamaya kopyalar. sk:update güncellemede yeniler.

Adım 5. Şunları kapsayan testler yazın:

• Stub yokken → vendor, tanımlı middleware katmanı altında otomatik mount yapar
• Stub varken → paket mount'u atlar (çift kayıt yok, route adı çakışması yok)
• Modüle özgü route adları doğru çözümlenir

registerRoutes() içinde başka bir bağlantıya gerek yoktur — döngü yeni descriptor'ı otomatik olarak alır.

Middleware Katmanı Referansı #

Yeni modüller middleware katmanlarını descriptor içinde açıkça tanımlamalıdır. check.permission middleware'ini gerektiren bir modül onu middleware dizisine eklemelidir — registry bunu otomatik olarak çıkarsamaz.