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:

composer require denizgolbas/laravel-tcmb-evds

Config Dosyasını Publish Etme

Config dosyasını publish etmek için:

php artisan vendor:publish --tag=evds-config

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

TCMB_EVDS_API_KEY=your-api-key-here
TCMB_EVDS_BASE_ENDPOINT=https://evds2.tcmb.gov.tr/service/evds/
TCMB_EVDS_NULL_HANDLING=previous_day

Ö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:

php artisan vendor:publish --tag=evds-migrations

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

php artisan migrate

Model'i Publish Etme

Model dosyasını publish etmek için:

php artisan vendor:publish --tag=evds-model

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

🛠️ Kullanım Örnekleri

Temel Kullanım

use Denizgolbas\LaravelTcmbEvds\Facades\Evds;

// Tek döviz kuru çekme (otomatik olarak hem alış hem satış, hem forex hem banknote)
$data = Evds::currency('USD')
    ->today()
    ->get();

// Çoklu döviz kuru çekme
$data = Evds::currency(['USD', 'EUR'])
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->get();

Alış/Satış Seçimi

// Sadece satış kurları (Forex Selling - Döviz Satış)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('sell')
    ->get();

// Sadece alış kurları (Forex Buying - Döviz Alış)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('buy')
    ->get();

// Hem alış hem satış (varsayılan)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->get();

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

// Sadece Forex kurları (Döviz)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->marketType('forex')
    ->get();

// Sadece Banknote kurları (Efektif)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->marketType('banknote')
    ->get();

// Hem forex hem banknote (varsayılan)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->get();

Kombinasyon Örnekleri

// Forex Satış (Döviz Satış)
$data = Evds::currency(['USD', 'EUR'])
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('sell')
    ->marketType('forex')
    ->get();

// Banknote Alış (Efektif Alış)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('buy')
    ->marketType('banknote')
    ->get();

// Banknote Satış (Efektif Satış)
$data = Evds::currency('EUR')
    ->today()
    ->type('sell')
    ->marketType('banknote')
    ->get();

Tarih Kısayolları

// Bugün
$data = Evds::currency('USD')->today()->get();

// Dün
$data = Evds::currency('USD')->yesterday()->get();

// Son 7 gün
$data = Evds::currency('USD')->lastDays(7)->get();

// Bu hafta
$data = Evds::currency('USD')->thisWeek()->get();

// Geçen hafta
$data = Evds::currency('USD')->lastWeek()->get();

// Bu ay
$data = Evds::currency('USD')->thisMonth()->get();

// Geçen ay
$data = Evds::currency('USD')->lastMonth()->get();

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

// Bir önceki günün değerini kullan (varsayılan)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->nullValueHandling('previous_day')
    ->get();

// Geçen haftanın ortalamasını kullan
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->nullValueHandling('last_week_avg')
    ->get();

// Null değerleri atla (kaydetme)
$data = Evds::currency('USD')
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->nullValueHandling('skip')
    ->get();

Veritabanına Kaydetme

// Basit kaydetme
$saved = Evds::currency('USD')
    ->today()
    ->save();

// Kombinasyonlu kaydetme
$saved = Evds::currency(['USD', 'EUR'])
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('sell')
    ->marketType('forex')
    ->nullValueHandling('previous_day')
    ->roundDecimals(2) // 2 ondalık basamağa yuvarla
    ->save();

// Kaydedilen verileri kullanma
foreach ($saved as $rate) {
    echo "{$rate->code}: {$rate->rate} ({$rate->date->format('Y-m-d')})\n";
    echo "Tip: {$rate->type}, Market: {$rate->marketType}\n";
}

URL Oluşturma

// URL'i görmek için
$url = Evds::currency(['USD', 'EUR'])
    ->startDate('2024-01-01')
    ->endDate('2024-01-10')
    ->type('sell')
    ->marketType('forex')
    ->build();

echo $url;
// Çıktı: https://evds2.tcmb.gov.tr/service/evds/series=TP.DK.USD.S.YTL-TP.DK.EUR.S.YTL&startDate=01-01-2024&endDate=10-01-2024&type=json

Model ile Veritabanından Veri Çekme

use Denizgolbas\LaravelTcmbEvds\Models\EvdsCurrencyRate;
use Carbon\Carbon;

// Bugünün USD kuru
$rate = EvdsCurrencyRate::where('code', 'USD')
    ->where('date', Carbon::today())
    ->first();

// Belirli bir tarih aralığındaki kurlar
$rates = EvdsCurrencyRate::where('code', 'USD')
    ->whereBetween('date', ['2024-01-01', '2024-01-10'])
    ->get();

// Sadece satış kurları
$sellRates = EvdsCurrencyRate::where('code', 'USD')
    ->sell()
    ->get();

// Sadece forex kurları
$forexRates = EvdsCurrencyRate::where('code', 'USD')
    ->forex()
    ->get();

// Kombinasyon: USD Forex Satış
$usdForexSell = EvdsCurrencyRate::where('code', 'USD')
    ->sell()
    ->forex()
    ->whereBetween('date', ['2024-01-01', '2024-01-10'])
    ->orderBy('date', 'asc')
    ->get();

// En son kaydedilen USD kuru
$latestUsd = EvdsCurrencyRate::where('code', 'USD')
    ->latest('date')
    ->first();

// Her döviz için en son kurlar
$latestRates = EvdsCurrencyRate::whereIn('code', ['USD', 'EUR'])
    ->latest('date')
    ->get()
    ->groupBy('code');

Gerçek Dünya Örnekleri

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

use Denizgolbas\LaravelTcmbEvds\Facades\Evds;

// Her gün çalışacak bir scheduled task
public function handle()
{
    // USD, EUR, GBP için bugünün kurlarını çek ve kaydet
    $saved = Evds::currency(['USD', 'EUR', 'GBP'])
        ->today()
        ->type('sell')
        ->marketType('forex')
        ->nullValueHandling('previous_day')
        ->save();

    return "{$saved->count()} adet kur kaydedildi.";
}

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

use Denizgolbas\LaravelTcmbEvds\Facades\Evds;

$data = Evds::currency(['USD', 'EUR'])
    ->startDate('2024-01-01')
    ->endDate('2024-01-31')
    ->type('sell')
    ->marketType('forex')
    ->get();

$report = [];
foreach ($data as $item) {
    $report[$item->code][$item->date->format('Y-m-d')] = $item->rate;
}

return view('exchange-rates', ['report' => $report]);

Örnek 3: Model ile Veri Analizi

use Denizgolbas\LaravelTcmbEvds\Models\EvdsCurrencyRate;

// Son 30 günün ortalama USD kuru
$avgRate = EvdsCurrencyRate::where('code', 'USD')
    ->sell()
    ->forex()
    ->where('date', '>=', Carbon::now()->subDays(30))
    ->avg('rate');

// En yüksek ve en düşük kurlar
$maxRate = EvdsCurrencyRate::where('code', 'USD')
    ->sell()
    ->forex()
    ->max('rate');

$minRate = EvdsCurrencyRate::where('code', 'USD')
    ->sell()
    ->forex()
    ->min('rate');

Örnek 4: Hata Yönetimi

use Denizgolbas\LaravelTcmbEvds\Facades\Evds;
use Denizgolbas\LaravelTcmbEvds\Exceptions\InvalidConfigurationException;
use Denizgolbas\LaravelTcmbEvds\Exceptions\ApiException;

try {
    $data = Evds::currency('USD')
        ->today()
        ->get();
} catch (InvalidConfigurationException $e) {
    // API key eksik veya yanlış yapılandırılmış
    logger()->error('EVDS Config Error: ' . $e->getMessage());
    return response()->json(['error' => 'API yapılandırma hatası'], 500);
} catch (ApiException $e) {
    // API isteği başarısız
    logger()->error('EVDS API Error: ' . $e->getMessage());
    return response()->json(['error' => 'API isteği başarısız'], 500);
} catch (\Exception $e) {
    // Genel hata
    logger()->error('EVDS Error: ' . $e->getMessage());
    return response()->json(['error' => 'Beklenmeyen bir hata oluştu'], 500);
}

📚 Builder Metodları Referansı

currency(array|string $codes)

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

Evds::currency('USD')->get();
Evds::currency(['USD', 'EUR', 'GBP'])->get();

startDate(Carbon|string $date)

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

Evds::currency('USD')->startDate('2024-01-01')->get();
Evds::currency('USD')->startDate(Carbon::parse('2024-01-01'))->get();

endDate(Carbon|string $date)

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

Evds::currency('USD')->endDate('2024-01-10')->get();

type(array|string $types)

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

Evds::currency('USD')->type('sell')->get();
Evds::currency('USD')->type('buy')->get();
Evds::currency('USD')->type(['buy', 'sell'])->get();

marketType(array|string $marketTypes)

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

Evds::currency('USD')->marketType('forex')->get();
Evds::currency('USD')->marketType('banknote')->get();
Evds::currency('USD')->marketType(['forex', 'banknote'])->get();

nullValueHandling(string $strategy)

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

Evds::currency('USD')->nullValueHandling('previous_day')->get();
Evds::currency('USD')->nullValueHandling('last_week_avg')->get();
Evds::currency('USD')->nullValueHandling('skip')->get();

build() veya toUrl()

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

$url = Evds::currency('USD')->today()->build();

get()

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

$data = Evds::currency('USD')->today()->get();

save()

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

// Basit kaydetme (API'den gelen değer olduğu gibi kaydedilir)
$saved = Evds::currency('USD')->today()->save();

// Ondalık basamak sayısını yuvarlayarak kaydetme
$saved = Evds::currency('USD')
    ->today()
    ->roundDecimals(2) // 2 ondalık basamağa yuvarla (örn: 45.67)
    ->save();

// Farklı yuvarlama modları
$saved = Evds::currency('USD')
    ->today()
    ->roundDecimals(2, 'floor') // Aşağı yuvarla (örn: 45.67 -> 45.67, 45.678 -> 45.67)
    ->save();

$saved = Evds::currency('USD')
    ->today()
    ->roundDecimals(2, 'ceil') // Yukarı yuvarla (örn: 45.67 -> 45.67, 45.671 -> 45.68)
    ->save();

🧪 Testler

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

composer test

veya

vendor/bin/phpunit --testdox

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:

return [
    'api_key' => env('TCMB_EVDS_API_KEY', ''),
    'base_endpoint' => env('TCMB_EVDS_BASE_ENDPOINT', 'https://evds2.tcmb.gov.tr/service/evds/'),
    'default_currencies' => ['USD', 'EUR', 'GBP'],
    'default_start_date' => null,
    'default_end_date' => null,
    'default_frequency' => 'daily',
    'null_value_handling' => env('TCMB_EVDS_NULL_HANDLING', 'previous_day'),
    'model' => \Denizgolbas\LaravelTcmbEvds\Models\EvdsCurrencyRate::class,
];

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:

'model' => \App\Models\CustomCurrencyRate::class,

Kendi modeliniz EvdsCurrencyRate modelini extend etmelidir:

namespace App\Models;

use Denizgolbas\LaravelTcmbEvds\Models\EvdsCurrencyRate as BaseModel;

class CustomCurrencyRate extends BaseModel
{
    // Özelleştirmeleriniz
}

🔧 Geliştirme

Gereksinimler

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

Geliştirme Ortamı Kurulumu

git clone https://github.com/denizgolbas/laravel-tcmb-evds.git
cd laravel-tcmb-evds
composer install

Kod Standartları

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

composer lint

📄 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: info@denizgolbas.com

🙏 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!