Bir PHP projesinde veritabanı sorguları önce controller içinde birkaç satırla başlayabilir. Uygulama büyüdükçe aynı kayıtları farklı ekranlar ister, filtreler çoğalır ve iş kuralları sorgularla karışır. Repository Pattern bu noktada veri erişimini açık bir sınırın arkasına almayı önerir. Fakat her modele otomatik olarak bir repository sınıfı eklemek yazılımı mutlaka iyileştirmez. Asıl soru şudur: Veri erişimindeki tekrar, değişim veya test ihtiyacı yeni bir soyutlamanın maliyetini karşılıyor mu?
Bu rehber Repository Pattern’in temel rolünü, controller–service–repository ayrımını, PHP ile basit uygulamasını, Laravel Eloquent ile ilişkisini ve sık yapılan hataları gösterir. Hazır bir şablonun her projeye uygulanmasını savunmak yerine karar ölçütleri vereceğiz. Böylece küçük bir blogu gereksiz sınıflarla doldurmadan, daha karmaşık iş akışlarında sorgu ve iş mantığını yönetilebilir tutabilirsiniz.
Repository Pattern nedir?
Repository, uygulamanın veri erişimiyle konuştuğu bir sınırdır. Bir servis “etkin kullanıcıyı bul”, “taslakları listele” veya “siparişi kaydet” gibi amaçlı işlemler çağırır; sorgu ayrıntısı repository içinde kalır. Bu sınır, veritabanı tablosunu doğrudan uygulamanın her yerine taşımamaya yardım eder. Soyutlama özellikle aynı seçme veya kaydetme kuralı birçok yerde tekrarlandığında yararlı olur. Ancak repository yalnızca findById(), save() ve delete() çağrılarını mevcut ORM’ye ileten ince bir katmansa ek değer sunmayabilir.
Deseni anlamak için “veritabanını yarın değiştiririz” iddiasına yaslanmak gerekmez. Çoğu projede tüm veri motorunu değiştirmek nadirdir. Daha gerçekçi yararlar, karmaşık sorguyu tek yerde tanımlamak, veri erişimini iş kuralından ayırmak, uygun test sınırı kurmak ve aynı kavram için tutarlı bir API sunmaktır. Bu yararlardan hiçbiri mevcut değilse doğrudan PDO veya Eloquent kullanmak daha açık olabilir.
Hangi sorumluluk hangi katmanda kalmalı?
Controller HTTP isteğini alır, girdiyi uygun şekilde doğrular ve sonucu yanıt biçimine çevirir. Service, “bu kullanıcı siparişi iptal edebilir mi?” gibi iş kararlarını ve birden çok adımı yönetir. Repository ise kayıtları okur veya yazar; fiyat hesabı, e-posta gönderimi, izin politikası veya HTML üretimi onun görevi değildir. Bu ayrım mutlak sınıf sayısı kuralı değildir. Çok küçük bir uç noktada controller doğrudan modele başvurabilir; gereksiz servis ve repository eklemek yalnızca dosya sayısını artırır.
İş akışını örnekleyelim: Kullanıcı bir makaleyi yayımlamak ister. Controller yazı kimliğini ve isteği doğrular. Service yazar yetkisini, yayımlama koşullarını ve işlem sırasını kontrol eder. Repository yazıyı bulur, durumunu kaydeder ve gerekirse ilgili sorguları çalıştırır. E-posta veya arama indeksleme başka bileşene gider. Her sınıf kendi rolünü koruduğunda bir hata için nereye bakılacağı nettir. Bu sınırlar adlandırılmış, küçük metotlarla daha anlaşılır hale gelir.
Repository sözleşmesi nasıl tasarlanır?

İlk adım tüm tablolara aynı genel arayüzü dayatmak değildir. Kullanım senaryosundan başlayın: publishedByAuthor(), findActiveByEmail() veya save() gibi çağıranın işine yarayan işlemler yazın. Metot adı sorgunun niyetini anlatmalı; “her şey için tek search($filters)” metodu kısa sürede sınırsız seçenek torbasına dönüşebilir. Dönüş tipi, bulunamama davranışı, sayfalama ve hata koşulları sözleşmenin parçasıdır. Bir metot kayıt yoksa null dönerken diğeri istisna fırlatıyorsa bu fark açık olmalıdır.
Arayüz kullanmak, yalnızca ikinci bir uygulama varsa zorunlu değildir. Yine de servis testlerinde sahte uygulama yazma, veri kaynağını ayırma veya modül sınırı oluşturma ihtiyacı varsa dar bir arayüz yararlı olabilir. Arayüzü altyapının bütün özelliklerini saklayan dev bir katalog gibi değil, kullanım alanının ihtiyacını karşılayan küçük bir sözleşme gibi tasarlayın. Arayüzde ORM’nin Builder veya Collection türlerini açığa çıkarmak, bağımlılığı gizlediğiniz iddiasını zayıflatır. Gerçekte ORM’ye bağlı kalacaksanız bunu dürüstçe kabul edin; soyutlama tasarımını sahte bağımsızlık için zorlamayın.
PHP ile basit bir repository örneği
Framework kullanmayan bir uygulamada PDO ile çalışan sınıf göstermek yeterlidir. Örneğin ArticleRepository kurucusunda bir PDO nesnesi alır, findPublishedBySlug(string $slug): ?array metodu parametreli sorgu çalıştırır ve bulunamazsa null döner. Slug değeri SQL cümlesine eklenmez, hazırlanmış sorguya parametre olarak bağlanır. Bu, kullanıcı girdisini SQL yapısından ayırır. Sorgu yalnızca yayımlı kayıtları getiriyorsa bu koşul metot adında veya açık açıklamada görünmelidir.
Kayıt yazma işleminde de benzer disiplin gerekir. saveDraft() ile publish() aynı işlem olmayabilir; yayımlama ek izin veya doğrulama gerektirir. Repository yalnızca veri yazımıyla ilgileniyorsa publish() iş kararını servis üstlenir, repository daha dar updateStatus() sağlar. Ancak alan dili içinde “yayımla” veri işleminin doğal bir parçasıysa sorumluluk sınırını belgede açıkça tanımlayın. Adlandırmadan daha önemli olan, iş kuralının farklı sınıflara parçalanıp izlenemez hale gelmemesidir.
Laravel Eloquent varken repository gerekir mi?
Laravel Eloquent zaten model, sorgu oluşturma, ilişki ve kayıt yaşam döngüsü için güçlü bir arayüz sunar. Basit CRUD ekranında yalnızca UserRepository::find($id) ile User::find($id) arasında yönlendirme yapmak çoğu kez gereksizdir. Eloquent kullanımı uygulamanın bilinçli mimari kararıysa bu bağımlılığı her satırda ikinci bir katmanla saklamak bakım yükünü artırabilir. Karmaşık, tekrarlanan sorgular için önce query scope veya özel sorgu sınıfı yeterli olabilir.
Repository, birden çok veri kaynağını birleştirdiğinizde, aynı alan sorgularını çok sayıda kullanım senaryosu paylaştığında ya da modül sınırını gerçekten korumak istediğinizde değer kazanır. Servislerin Eloquent modelini hiç görmemesi hedefleniyorsa repository dönüşlerinde alan nesneleri veya açık veri taşıyıcıları kullanmanız gerekebilir. Bu daha büyük bir tasarım kararıdır; dönüşümleri, ilişkileri ve performans etkisini planlayın. Laravel’in Eloquent belgeleri mevcut yetenekleri gösterir. Önce bu yetenekleri anlayın, sonra eksik kalan sınırı kurun.
Genel repository mi, alana özel repository mi?
Her tablo için BaseRepository mirası oluşturmak kolay görünür: ekle, bul, güncelle ve sil. Fakat gerçek kullanım kısa sürede “yayındaki ve erişilebilir kayıtları tarihe göre sırala” gibi alana özgü bir sorgu ister. Genel temel sınıf bu ayrıntıyı gizlemek için karmaşık filtre dizilerine dönüşebilir. Alana özel repository daha az yeniden kullanım vaat eder, fakat çağıran kodu daha anlaşılır kılar. Hangi yaklaşımın uygun olduğu uygulamanın tekrar biçimine bağlıdır; yalnızca satır tekrarını azaltmak tek hedef olmamalıdır.
Ortak temel sınıf kullanacaksanız sadece mekanik, kararlı davranışı paylaşın. İş kurallarını bu sınıfa taşımayın. Bir kullanıcının silinmesinin hesap kapanması, veri anonimleştirme veya başka bir süreç anlamına geldiği üründe genel delete() metodunun her yerden çağrılabilmesi risklidir. Uygulamanın dilini taşıyan metotlar, yanlış işlemi çağırmayı da zorlaştırır. Tasarımın iyi olup olmadığını sınıf hiyerarşisinin şıklığına değil, kullanım kodunun açıklığına bakarak değerlendirin.
Transaction sınırı nerede olmalı?
Bir kullanım senaryosu birden çok repository çağırıyorsa transaction sınırı genellikle bu senaryoyu yöneten servis veya uygulama katmanında olmalıdır. Sipariş oluşturup stok düşmek iki ayrı veri değişikliğidir; her repository kendi içinde bağımsız transaction açarsa bütünü atomik tutmak zorlaşır. Laravel’de veritabanı transaction araçları bu akışı tek işlem altında yönetmeye imkân verir. PDO kullanan uygulamada da beginTransaction(), commit() ve hata durumunda rollBack() uygun yerde çağrılmalıdır.
Repository yöntemlerinin transaction içinde çağrılabileceğini belgeleyin. Bir yöntem kendi içinde gizlice işlem başlatıyorsa üst katmandaki bütünlüğü bozabilir. Harici API çağrısı veya e-posta gönderimi veritabanı transaction’ıyla otomatik geri alınmaz; bunu ayrı bir teslim stratejisiyle ele alın. Özellikle “kayıt yazıldı fakat mesaj gidemedi” durumunu düşünmeden kodu katmanlara dağıtmak, desenden beklenen düzeni sağlamaz.
Listeleme, filtreleme ve sayfalama
Repository tasarımında en zor bölüm çoğu zaman findById() değil, liste ekranıdır. Kullanıcı tarih aralığı, durum, kategori ve arama terimiyle süzebilir. Her olasılık için ayrı metot açmak patlar; sınırsız bir dizi geçirmek ise sözleşmeyi anlamsızlaştırır. Kısıtlı ve doğrulanmış bir filtre nesnesi iyi bir orta yoldur. Örneğin ArticleFilter yalnızca izin verilen durumları, yazarı, tarih sınırını ve sayfa boyutunu taşır. Repository bu nesneyi sorguya çevirir.
Sayfa boyutuna üst sınır koyun ve varsayılan sıralamayı belirleyin. Eşit tarihli satırlar için kimlik gibi ikinci sıralama anahtarı ekleyin; aksi halde kayıtlar sayfalar arasında yer değiştirebilir. Büyük tabloda derin OFFSET sayfaları pahalılaşır; uygun yerde imleçli sayfalama değerlendirin. Kullanıcıya dönecek alanları da ihtiyaca göre seçin. Her listede tüm ilişkileri yüklemek, repository katmanının performans sorununu saklamasına yol açar.
Önbellek ve farklı veri kaynakları
Bir repository’nin önüne önbellek katmanı koymak tekrar eden okumaları hızlandırabilir. Fakat önbellek, sözleşmenin tutarlılık beklentisini değiştirir. Kullanıcı bir yazıyı güncelledikten sonra kendi ekranında eski başlığı ne kadar süre görebilir? Bu soruya cevap vermeden CachedArticleRepository eklemek hatalı veriyi çoğaltabilir. Önce hangi okumanın sık olduğunu ölçün, sonra anahtar, süre ve geçersiz kılma kuralını belirleyin. Kritik yetki kararlarını eski kalabilecek önbellek verisine dayandırmayın.
SQL ve harici API gibi kaynakları aynı repository arkasında toplamak bazen yararlıdır, fakat gecikme ve hata davranışı farklıdır. Veritabanı sorgusu milisaniyeler sürerken dış servis zaman aşımına uğrayabilir. Çağıranın bu farkı bilmesi gerekiyorsa tek tip arayüz sorunları gizleyebilir. Kaynakları birleştirme işini servis veya özel bir veri toplama bileşeninde yapmak daha açık olabilir. Soyutlama, gerçek sınırı görünmez kılmak için değil, kullanım senaryosunun kararını kolaylaştırmak için vardır.
Repository ne zaman gerçekten yararlı?

Aynı karmaşık sorgu birden fazla kullanım senaryosunda yineleniyorsa, veri kaynağı veya saklama biçimi farklılaşabiliyorsa, çok modüllü sistemde veri sahipliği korunmak isteniyorsa repository yararlı olabilir. Testlerde belirli veri erişim davranışını kontrollü şekilde değiştirmek de gerekçe olabilir. Bunun karşısında tek tabloyla çalışan küçük bir yönetim ekranı, sabit ORM kullanan ve tekrarı düşük bir uygulama için doğrudan model kullanımı daha az maliyetlidir. Kararı “büyük proje” etiketiyle değil, somut değişim noktalarıyla verin.
Yeni sınıf eklemeden önce mevcut kodu inceleyin: aynı sorgu kaç yerde var, hangi kurallar birbirinden farklı, değişiklik yaparken kaç dosyaya dokunuluyor? Eğer cevap tek bir ortak sorguysa bir query scope yeterli olabilir. Eğer birden çok veri erişim yolu aynı alan sözleşmesine uymak zorundaysa repository daha güçlü bir adaydır. Gereksinim değiştikçe kararı yeniden değerlendirin. Başta doğrudan ORM kullanmak, ileride repository eklenemeyeceği anlamına gelmez; gereksiz erken soyutlama da ileride kaldırılabilir.
Nasıl test edilir?
Repository’nin kendisini gerçek veritabanına yakın koşullarda sınayın. Parametreli sorgu, boş sonuç, sınır tarihleri, yetkisiz tenant, sıralama ve sayfalama davranışı test edilmelidir. Yalnızca sahte repository ile yapılan test, gerçek sorgudaki kolon veya ilişki hatasını bulamaz. Servis testinde ise repository arayüzünü sahteleyerek iş kararını izole etmek yararlı olabilir. Bu iki test türü farklı soruları yanıtlar; birinin varlığı ötekini gereksiz kılmaz.
Bir test veritabanı kullanırken migration’ları çalıştırın, gerekli indeks ve benzersiz kısıtların davranışını kontrol edin. SQLite ile test edip üretimde farklı bir motor kullanıyorsanız sözdizimi ve sıralama farklarına dikkat edin. Hata yolunu da sınayın: kayıt bulunamadığında servis ne yapıyor, transaction geri alınıyor mu, harici çağrı başarısızsa veri tutarlı mı? Testleri yalnızca repository’nin mevcut kodunu tekrar eden onay cümlelerine dönüştürmeyin; gerçek kullanım sonuçlarını doğrulayın.
En sık yapılan hatalar
İlk hata, her model için içi boş bir arayüz ve aynı isimli uygulama üretmektir. Bu durum dosya sayısını artırır, ancak sorgu tekrarı veya iş sınırı sorununu çözmez. İkinci hata, iş kurallarını repository’ye taşımaktır; veri erişimi ile karar verme karışır. Üçüncüsü, tüm çağıranlara ham ORM sorgu nesnesi döndürüp “soyutladık” demektir. Çağıran kod yine sorgu ayrıntısını bilir. Dördüncüsü, genel filtre metodu içine her yeni koşulu ekleyip tip ve doğrulama sınırını kaybetmektir.
Beşinci hata, repository testlerini yalnızca mock üzerinden yapmaktır. Gerçek SQL çalışmadığı için performans ve sorgu hataları kaçabilir. Altıncısı, transaction sınırını her repository metoduna gizleyip çok adımlı iş akışında atomikliği kaybetmektir. Yedincisi, deseni kullanmanın tek gerekçesini “bir gün veritabanı değişebilir” olarak yazmaktır. Gelecekteki belirsiz ihtimal uğruna bugünkü okunabilirliği azaltmayın. Somut tekrar, değişim ve test ihtiyacı kararın ana dayanağı olsun.
Mevcut projeye nasıl adım adım eklersiniz?
Çalışan bir uygulamayı tek seferde yeni mimariye taşımaya çalışmayın. Önce tekrarlanan ve sık değişen tek bir sorgu ailesi seçin. Sorgunun tüm çağıranlarını listeleyin, bugün hangi filtre ve sıralama davranışını verdiğini testle sabitleyin. Sonra bu davranışı karşılayan küçük bir repository metodu oluşturun ve ilk çağıranı taşıyın. Üretim sonucunu karşılaştırın; kayıt sayısı, sıralama ve boş sonuç davranışı değişmediyse diğer çağıranlara geçin. Eski sorguyu her yer taşındıktan sonra kaldırın. Bu sıralama, refaktör sırasında iki farklı gerçeğin uzun süre yaşamasını önler.
Servislerin hepsi aynı anda değişmek zorunda değildir. Bir alanda doğrudan Eloquent, diğerinde repository bulunması geçiş döneminde kabul edilebilir; hedefin ve kalan işin takip edilmesi önemlidir. Eski kodu “mimari tutarsızlık” gerekçesiyle körlemesine taşımak yerine, her değişikliğin gözlenen bir yararı olsun. Repository eklendikten sonra sorgu sayısı ve yanıt süresi artıyorsa ilişkilerin tembel yüklenmesi veya gereksiz dönüşüm oluşmuş olabilir. Düzenli kod incelemesinde arayüzün gerçek çağıran ihtiyacını yansıtıp yansıtmadığını sorun.
Yetki ve çok kiracılı veri sınırı
Çok kiracılı bir uygulamada yalnızca findById($id) metodu, başka kuruluşa ait kaydı yanlışlıkla döndürebilir. Çağrı sözleşmesine kuruluş bağlamı eklemek veya erişim kapsamını merkezi uygulamak gerekir. Bu durum repository’nin yetki kararını tek başına vermesi anlamına gelmez. Service kullanıcının hangi kuruluşa erişebildiğini belirler; repository o kapsam dışındaki kaydı getirmez. Her iki sınırı test edin. Yanlış tenant kimliğine ait bir kaydın okunması veya güncellenmesi, veri erişimi soyutlaması ne kadar şık olursa olsun ciddi bir tasarım hatasıdır.
Özellikle genel update($id, $data) metotları, kapsamı gizleyebildiği için dikkat ister. Güncelleme sorgusunda kuruluş koşulu bulunmalı, etkilenen satır sayısı kontrol edilmeli ve sıfır sonuç için açık davranış seçilmelidir. Kullanıcıya ait olmayan kaydı “bulunamadı” gibi göstermek bazı ürünlerde bilgi sızmasını azaltabilir; bu karar servis ve API yanıt katmanıyla birlikte verilmelidir. Sorgu sınırlarını test verisinde en az iki farklı kuruluş oluşturarak sınayın. Tek kuruluşla geçen test, bu hatayı yakalayamaz.
Adım adım uygulama kontrol listesi
Önce bir kullanım senaryosu seçin ve sorgunun bugün kaç yerde tekrarlandığını ölçün. Controller, servis ve veri erişimi sorumluluklarını cümlelerle yazın. Küçük, alana özgü metot adları belirleyin; dönüş ve hata davranışını açıkça tanımlayın. Repository’yi PDO veya mevcut ORM üzerinde uygulayın, tüm kullanıcı girdilerini güvenli parametreleme ve doğrulamadan geçirin. Transaction sınırını bütün iş akışını gören yerde tutun. Liste sorgularına sayfalama ve kararlı sıralama ekleyin. Son olarak servis ve gerçek veri erişimi testlerini ayrı ayrı çalıştırın.
Refaktör sonrası kodu yeniden okuyun. Yeni bir sorgu eklemek daha kolay mı? Bir kullanım senaryosunu anlamak için daha az dosyaya mı bakıyorsunuz? Değişiklik yalnızca daha çok katman ürettiyse soyutlamayı sadeleştirin. Repository Pattern iyi kullanıldığında veri erişiminin niyetini görünür kılar; kötü kullanıldığında mevcut ORM’nin kopyası olur. PHP projenizde doğru karar, desenin adını uygulamak değil, bakım maliyetini gerçekten düşüren sınırı kurmaktır.


