Download the PHP package denizgolbas/laravel-tcmb-evds without Composer

Laravel TCMB EVDS2 Günlük Döviz Kurları Paketi

🇹🇷 Türkçe | 🇬🇧 English

TCMB EVDS2 API'sinin "Günlük Döviz Kurları (Daily FX Rates)" servisine özel geliştirilmiş, modern bir Laravel paketi.

Paket, chainable bir URL/Query Builder, esnek bir API istemcisi, publish edilebilir migration + model yapısı ve isteğe bağlı olarak gelen verilerin veritabanına kaydedilmesini destekler.

Bu paket; proje içinde kolayca günlük döviz kurlarını çekmek, işlemek, saklamak ve otomatikleştirmek isteyen Laravel geliştiricileri için tasarlanmıştır.

⚠️ ÖNEMLİ UYARI

Bu paket resmi TCMB EVDS2 API'sine bağlanmak ve kurları kolayca işleyebilmek için oluşturulmuş bir araçtır. Resmi bir dağıtım değildir.

Kullanımda doğacak finansal hatalar ve kayıplar sizin sorumluluğunuzdadır.

• Bu paket TCMB tarafından resmi olarak desteklenmemektedir
• Finansal işlemlerde kullanmadan önce mutlaka doğrulama yapın
• Kritik finansal kararlar için resmi TCMB kaynaklarını kullanın
• Paket kullanımından kaynaklanan herhangi bir zarardan paket geliştiricileri sorumlu değildir

🚀 Özellikler

• 🔗 Fluent URL Builder - TCMB EVDS2 endpoint'ini zincir fonksiyonlar ile kolayca oluşturun
• 📅 Hazır Tarih Kısayolları - today(), yesterday(), lastDays(7), thisMonth() gibi fonksiyonlarla hızlı tarih aralıkları
• 💾 Opsiyonel Database Kaydı - API'den gelen döviz kurlarını model ile veritabanına kaydedebilirsiniz
• ⚙️ Publish Edilebilir Model ve Migration - İsterseniz kendi projenizde model/migration dosyalarını özelleştirin
• 🧩 Config Tabanlı Esneklik - Varsayılan dövizler, tarih ayarları ve API key config üzerinden yönetilir
• 🎯 Alış/Satış ve Forex/Banknote Ayrımı - Döviz alış, döviz satış, efektif alış, efektif satış kurlarını ayrı ayrı çekebilirsiniz
• 🔄 Null Değer Yönetimi - Hafta sonları ve tatil günleri için esnek null değer işleme stratejileri
• 🧪 Unit, Feature ve Matrix Testleri - Laravel 10/11 + PHP 8.2/8.3 kombinasyonları için GitHub Actions test workflow'u
• 📡 Laravel Http Client ile API İletişimi - Temiz, güvenli ve performanslı bir API client

📦 Kurulum

Paketi Composer ile yükleyin:

Config Dosyasını Publish Etme

Config dosyasını publish etmek için:

Bu işlem config/evds.php dosyasını oluşturur. .env dosyanıza API anahtarınızı ekleyin:

Önemli: API anahtarınızı TCMB EVDS2 Kullanıcı Dokümanları sayfasından alabilirsiniz.

Migration'ları Publish Etme

Migration dosyalarını publish etmek için:

Ardından migration'ları çalıştırın:

Model'i Publish Etme

Model dosyasını publish etmek için:

Bu işlem app/Models/EvdsCurrencyRate.php dosyasını oluşturur. İsterseniz bu modeli extend ederek özelleştirebilirsiniz.

🛠️ Kullanım Örnekleri

Temel Kullanım

Alış/Satış Seçimi

Forex/Banknote (Döviz/Efektif) Seçimi

Kombinasyon Örnekleri

Tarih Kısayolları

Null Değer Yönetimi (Hafta Sonları ve Tatil Günleri)

Veritabanına Kaydetme

URL Oluşturma

Model ile Veritabanından Veri Çekme

Gerçek Dünya Örnekleri

Örnek 1: Günlük Döviz Kurlarını Çekip Kaydetme

Örnek 2: Belirli Tarih Aralığındaki Kurları Raporlama

Örnek 3: Model ile Veri Analizi

Örnek 4: Hata Yönetimi

📚 Builder Metodları Referansı

currency(array|string $codes)

Döviz kodlarını ayarlar. Tek veya çoklu döviz kodu kabul eder.

startDate(Carbon|string $date)

Başlangıç tarihini ayarlar. Carbon instance veya string formatında tarih kabul eder.

endDate(Carbon|string $date)

Bitiş tarihini ayarlar. Carbon instance veya string formatında tarih kabul eder.

type(array|string $types)

Alış/Satış tipini ayarlar. 'buy', 'sell' veya ['buy', 'sell'] kabul eder.

marketType(array|string $marketTypes)

Market tipini ayarlar. 'forex', 'banknote' veya ['forex', 'banknote'] kabul eder.

nullValueHandling(string $strategy)

Null değer işleme stratejisini ayarlar. 'previous_day', 'last_week_avg', 'skip' kabul eder.

build() veya toUrl()

URL'i oluşturur ve döndürür.

get()

API'den veri çeker ve Collection döndürür.

save()

API'den veri çeker ve veritabanına kaydeder. Collection döndürür.

🧪 Testler

Testleri çalıştırmak için:

veya

Test Kapsamı

• ✅ Builder URL oluşturma testleri
• ✅ Tarih metodları testleri
• ✅ API client testleri (mock ile)
• ✅ Database kayıt testleri
• ✅ Facade testleri
• ✅ Null değer yönetimi testleri

Matrix Testler

GitHub Actions üzerinde şu kombinasyonlar test edilir:

• PHP 8.2 + Laravel 10.x
• PHP 8.2 + Laravel 11.x
• PHP 8.3 + Laravel 10.x
• PHP 8.3 + Laravel 11.x

GitHub Actions için API Key Kurulumu

GitHub Actions'da testlerin çalışması için (opsiyonel - testler mock kullanır):

1. GitHub repository'nize gidin
2. Settings → Secrets and variables → Actions seçeneğine gidin
3. New repository secret butonuna tıklayın
4. Şu bilgileri girin:
   • Name: TCMB_EVDS_API_KEY
   • Secret: API anahtarınızı yapıştırın
5. Add secret butonuna tıklayın

Not: Testler için gerçek API key'e ihtiyaç yoktur çünkü testler mock response kullanır. Ancak gerçek API testleri yapmak isterseniz secret'ı ekleyebilirsiniz.

⚙️ Konfigürasyon

Config dosyası (config/evds.php) aşağıdaki ayarları içerir:

Null Değer Yönetimi

Hafta sonları ve tatil günleri için null değerlerin nasıl işleneceğini ayarlayabilirsiniz:

• 'previous_day': Bir önceki günün değerini kullan (varsayılan)
• 'last_week_avg': Geçen haftanın ortalamasını kullan
• 'skip': Null değerleri atla, kaydetme

Model Özelleştirme

Kendi modelinizi kullanmak için config dosyasında model ayarını değiştirin:

Kendi modeliniz EvdsCurrencyRate modelini extend etmelidir:

🔧 Geliştirme

Gereksinimler

• PHP >= 8.2
• Laravel >= 10.0
• Composer

Geliştirme Ortamı Kurulumu

Kod Standartları

Paket PSR-12 kod standartlarına uygundur. Kodları kontrol etmek için:

📄 Lisans

Bu paket MIT lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.

🤝 Katkıda Bulunma

Katkılarınızı bekliyoruz! Lütfen:

1. Fork edin
2. Feature branch oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi commit edin (git commit -m 'Add some amazing feature')
4. Branch'inizi push edin (git push origin feature/amazing-feature)
5. Pull Request oluşturun

📞 Destek

Sorularınız veya önerileriniz için:

• Issue açın: GitHub Issues
• Email: [email protected]

🙏 Teşekkürler

• TCMB EVDS2 API ekibine teşekkürler
• Laravel topluluğuna teşekkürler

⭐ Bu paketi beğendiyseniz yıldız vermeyi unutmayın!