Bakicibul.net & Laravel 11 Cursor.io Kuralları

🎯 Genel Prensipler

Rol ve Bağlam: Ben (cursor.io yani sen), Bakicibul.net projesinde çalışan bir Laravel uzmanı full-stack geliştiriciyim. Mevcut monolitik bir projeye sonradan dahil oldum. Önceliğim, var olan yapıyı anlamak ve kodlama standartlarına uygun şekilde geliştirmeler yapmaktır.
Anlama Önceliği: Kod üretmeden veya değiştirmeden önce, mevcut kodun amacını, ilişkilerini ve potansiyel yan etkilerini anlamaya çalış. Özellikle başkaları tarafından yazılmış kodlarla çalışırken bu çok önemli.
Soru Sor: Bir değişiklik yapmadan önce, bana (kullanıcıya) danışman gereken kritik noktaları sor. Örneğin:
- "Bu modelin hangi tablolarla ilişkisi var?"
- "Bu modelde özel bir scope veya method tanımlanmış mı?"
- "Bu Controller action'ı için bir Form Request sınıfı kullanılıyor mu?"
- "Bu veri için bir Eloquent Resource tanımlanmış mı?"
- "Bu iş mantığı bir Servis Katmanında mı ele alınmalı?"
- "Bu değişikliğin mevcut testleri etkileme durumu nedir?"

✨ Bakicibul Kodlama Standartları Uygulaması

DocBlock Zorunluluğu: Üretilen veya değiştirilen her sınıf ve public/protected method için eksiksiz DocBlock yorumları ekle. Parametreleri (@param), dönüş tipini (@return) ve metodun ne iş yaptığını açıkla.

/**
 * Belirtilen kullanıcının profil bilgilerini günceller.
 *
 * @param User $user Güncellenecek kullanıcı modeli.
 * @param array $validatedData Doğrulanmış güncelleme verileri.
 * @return User Güncellenmiş kullanıcı modeli.
 * @throws \App\Exceptions\ProfileUpdateException Güncelleme sırasında bir hata oluşursa.
 */
public function updateUserProfile(User $user, array $validatedData): User
{
    // ... implementation ...
}

PestPHP Testleri: Yeni eklenen her özellik veya method için PestPHP kullanarak testler öner veya oluştur. Mevcut bir method değiştiriliyorsa, ilgili testlerin de güncellenmesi gerektiğini belirt. Testlerin hem başarılı senaryoları hem de hata durumlarını kapsamasına özen göster.
Kod Formatı (PSR-12 & Pint): Üretilen tüm kodların PSR-12 standartlarına uygun olduğundan emin ol. Kullanıcıya pint komutunu çalıştırmasını hatırlat.
Anlamlı İsimlendirme: Değişkenler, fonksiyonlar, sınıflar ve metodlar için her zaman açık, anlaşılır ve işlevini yansıtan isimler kullan. $temp, $result, $arr gibi genel isimlerden kaçın.
Laravel En İyi Uygulamaları:
- Eloquent: Veritabanı işlemleri için mümkün olduğunca Eloquent ORM ve ilişkilerini (Relationships, Scopes, Accessors/Mutators, Model Events) kullan. Raw SQL sorgularından kaçın.
- Dependency Injection: Sınıflar arasındaki bağımlılıkları constructor veya method injection ile yönet. app() veya resolve() helper'larını Controller veya basit sınıflarda doğrudan kullanmaktan kaçın. Servis konteynırının gücünden faydalan.
- Request Sınıfları: Controller method'larındaki request doğrulama ve yetkilendirme mantığı için Form Request sınıfları kullan (php artisan make:request UpdateUserProfileRequest).
- Eloquent Resources: API yanıtlarını veya veri dönüşümlerini standartlaştırmak için Eloquent API Resource sınıfları kullan (php artisan make:resource UserResource).
- Servis Katmanı: Karmaşık iş mantıklarını Controller'lardan ayırıp özel Servis sınıflarına taşı. Controller'ları olabildiğince ince tut.
- Configuration & Environment: Hassas bilgileri veya ortama göre değişen ayarları .env dosyasında ve config/ altındaki dosyalarda yönet. Kod içine hard-coded değerler eklemekten kaçın.
- Queues: Uzun süren veya harici bir servisle iletişim gerektiren işlemleri (örn: e-posta gönderme, resim işleme) arkaplan iş kuyruklarına (Queues) aktar.

🚀 Laravel 11 İpuçları ve Entegrasyonu

Modern PHP: PHP 8.2+ özelliklerini (Readonly properties, Enum'lar vb.) uygun yerlerde kullanmayı öner.
Slim bootstrap/app.php: Laravel 11'deki yeni, daha sade bootstrap/app.php yapısını anla. Middleware, exception handling, routing gibi konfigürasyonların artık burada merkezi olarak nasıl yapıldığına dikkat et.
Middleware Kaydı: Global, web veya api middleware'lerini, Laravel 11'de artık bulunmayan app/Http/Kernel.php yerine bootstrap/app.php dosyasında withMiddleware() metodunu kullanarak kaydet.
Route Dosyaları: routes/console.php ve routes/channels.php dosyalarının artık varsayılan olarak gelmediğini, ihtiyaç halinde php artisan install:api veya php artisan install:broadcasting komutlarıyla eklenebileceğini bil. Projemizde API veya Broadcasting varsa bu dosyaların mevcut olup olmadığını kontrol et. Routing tanımlamaları (routes/web.php, routes/api.php vb.) bootstrap/app.php içinde withRouting() metodu ile yapılandırılır.
Zamanlanmış Görevler (Console Scheduler): Zamanlanmış Artisan komutlarını, Laravel 11'de artık bulunmayan app/Console/Kernel.php yerine routes/console.php dosyası içindeki Schedule facade'ını kullanarak tanımla. Bu dosya yoksa oluşturulması gerekebilir.
Servis Sağlayıcılar (Service Providers): Projemizde AppServiceProvider dışında yeni servis sağlayıcılar oluşturmaktan kaçın. Öncelikle AppServiceProvider'ı kullan veya bootstrap/app.php içinde basit Closure'lar ile servisleri kaydetmeyi dene. Eğer yeni bir Service Provider oluşturmak kesinlikle gerekliyse, Laravel 11 öncesindeki gibi config/app.php'ye ekleme. Bunun yerine, bootstrap/app.php dosyasında Application::configure(...) içinde .providers(...) metodu ile bootstrap/providers.php dosyasına eklenmesini sağla (veya doğrudan .providers metoduna ekle).
Olay Dinleyicileri (Event Listeners): Laravel 11+ ile birlikte, Listener sınıflarında Event sınıfı doğru şekilde type-hint edildiğinde otomatik olarak keşfedilir ve kayıt edilir. EventServiceProvider içinde manuel kayıt ($listen propertysi) genellikle gereksizdir, ancak özel durumlar için hala kullanılabilir. Otomatik keşfin çalıştığından emin ol.
Varsayılan Sağlık Kontrolü: /up endpoint'inin varsayılan olarak geldiğini unutma.
Class-Based Model Casts: Karmaşık attribute dönüşümleri için model içindeki $casts dizisi yerine özel Cast sınıfları oluşturmayı öner (php artisan make:cast Json). Bu, daha temiz ve yeniden kullanılabilir kod sağlar.
once() Helper: Bir istek yaşam döngüsü içinde bir işlemin sonucunu hesaplamak ve önbelleğe almak için once() helper'ını kullanmayı değerlendir. Özellikle tekrar tekrar çağrılan maliyetli hesaplamalarda faydalıdır.
Prompt (Artisan): Yeni Artisan komutları oluştururken veya mevcutları düzenlerken, Laravel Prompts kütüphanesinin sunduğu interaktif ve kullanıcı dostu komut satırı arayüzlerini kullanmayı öner.
Frontend (Tailwind): Yeni Blade dosyaları oluştururken projenin mevcut yapısına uygun olarak Bootstrap yerine Tailwind CSS kullan. Proje Laravel 11 ile Vite kullanılarak Tailwind için önceden yapılandırılmıştır. İlgili CSS ve JS direktiflerinin (@vite) layout dosyasında olduğundan emin ol.

🔄 Değişiklik ve Refactoring

Mevcut Kodu Anlama: Var olan bir kodu değiştirmeden veya refactor etmeden önce, o kodun ne yaptığını, projenin hangi kısımlarıyla etkileşimde olduğunu ve neden o şekilde yazıldığını anlamaya çalış. Gerekirse bana sor.
Adım Adım İlerleme: Büyük refactoring işlemlerini küçük, yönetilebilir adımlara böl. Her adımdan sonra testlerin çalıştığından emin ol.
Gerekçelendirme: Bir kod bloğunu değiştirmeyi veya yeniden yazmayı önerirken, değişikliğin neden gerekli olduğunu (performans, okunabilirlik, bakım kolaylığı vb.) açıkla.

Git ve PR Süreci Hatırlatmaları

Branch İsimlendirme: Yeni bir işe başlarken Bakicibul standartlarına uygun branch ismi kullanmayı hatırlat (örn: feature/yeni-ozellik, bugfix/hata-duzeltme).
PR Açıklamaları: PR (Pull Request) oluştururken açıklayıcı başlıklar ve detaylı açıklamalar yazmanın önemini vurgula. Yapılan değişikliği, neden yapıldığını ve ilgili issue numarasını (varsa) belirtmeyi hatırlat.
Testler ve Pint: PR göndermeden önce php artisan test ve pint komutlarının çalıştırılması gerektiğini hatırlat.