Laravel İle Dinamik Bir Çoklu Para Birimi Dönüştürücü Nasıl Yapılır?

Ön Hazırlık ve Gereksinimler

Başarılı bir uygulama geliştirmek için sisteminizde Laravel 11 veya üzeri bir sürümün kurulu olduğundan emin olmalısınız. Ayrıca, döviz kurlarını çekmek için ücretsiz veya ücretli bir API servisine (örneğin: ExchangeRate-API veya Open Exchange Rates) ihtiyacınız olacak.

• PHP 8.2+ sürümü
• Laravel 11 framework kurulumu
• Guzzle HTTP istemcisi (Laravel ile yüklü gelir)
• Bir döviz kuru API anahtarı (API Key)

Geliştirme ortamınızda .env dosyanızın hazır olduğundan emin olun. API anahtarınızı asla doğrudan kodun içine yazmayın; her zaman .env dosyasında saklayın.

Adım 1: API Servisi İçin Bir Hizmet Sınıfı (Service Class) Oluşturma

Laravel'de iş mantığını (business logic) Controller içinden ayırmak, kodun sürdürülebilirliği için kritiktir. Döviz kuru işlemlerini yönetecek bir CurrencyService sınıfı oluşturacağız. Bu sınıf, API ile haberleşecek ve veriyi işleyecektir.

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class CurrencyService
{
    protected $apiKey;

    public function __construct()
    {
        $this->apiKey = config('services.currency_api.key');
    }

    public function getExchangeRate($from, $to)
    {
        return Cache::remember("rate_{$from}_{$to}", 3600, function () use ($from, $to) {
            $response = Http::get("https://api.exchangerate-api.com/v4/latest/{$from}");
            return $response->json()['rates'][$to] ?? null;
        });
    }
}

Bu kodda Cache::remember kullanarak, her istekte API'ye gitmek yerine kur verisini 1 saat boyunca bellekte tutuyoruz. Bu, uygulamanızın performansını ciddi oranda artırır ve API limitlerinizi korur.

Adım 2: Konfigürasyon ve Güvenlik Ayarları

API anahtarınızı yönetmek için config/services.php dosyasını kullanmalısınız. Bu, uygulamanızın yapılandırmasını merkezi bir yerden yönetmenizi sağlar.

// config/services.php içinde
'currency_api' => [
    'key' => env('CURRENCY_API_KEY'),
],

Ardından .env dosyanıza şu satırı ekleyin:

CURRENCY_API_KEY=sizin_api_anahtariniz_buraya

Güvenlik Uyarısı: .env dosyanızı asla versiyon kontrol sistemlerine (Git gibi) dahil etmeyin. API anahtarlarınızı çevresel değişkenlerde tutmak, kodunuzu paylaşırken kimlik bilgilerinizi korumanın en güvenli yoludur.

Adım 3: Controller İçinde Dönüştürme Mantığını Uygulama

Servis sınıfımızı oluşturduktan sonra, bunu bir Controller üzerinden çağırmamız gerekir. Kullanıcıdan gelen "hangi para birimine çevrilecek?" bilgisini alıp sonucu döndüren bir yapı kuracağız.

namespace App\Http\Controllers;

use App\Services\CurrencyService;
use Illuminate\Http\Request;

class CurrencyController extends Controller
{
    public function convert(Request $request, CurrencyService $service)
    {
        $request->validate([
            'amount' => 'required|numeric',
            'from' => 'required|string|size:3',
            'to' => 'required|string|size:3',
        ]);

        $rate = $service->getExchangeRate($request->from, $request->to);
        $result = $request->amount * $rate;

        return response()->json(['converted_amount' => $result]);
    }
}

Burada $request->validate kullanarak gelen verinin doğruluğunu kontrol ediyoruz. Bu, SQL Injection veya geçersiz veri girişlerine karşı ilk savunma hattımızdır.

Adım 4: Performans Karşılaştırması: Önbellekleme Yöntemleri

Döviz kuru gibi sık değişmeyen verilerde doğru önbellekleme stratejisi seçmek, uygulamanızın hızını belirler. Aşağıdaki tablo, farklı yaklaşımların avantaj ve dezavantajlarını özetlemektedir.

Adım 5: Frontend Entegrasyonu ve Dinamik Güncelleme

Kullanıcıların sayfayı yenilemeden fiyatları görmesi için JavaScript (Fetch API veya Axios) kullanmalısınız. Laravel'in sunduğu axios kütüphanesi bu iş için idealdir.

// Basit bir JavaScript örneği
async function convertCurrency(amount, from, to) {
    const response = await axios.post('/api/convert', { amount, from, to });
    document.getElementById('result').innerText = response.data.converted_amount;
}

Bu kod, arka planda Laravel rotanıza bir POST isteği gönderir ve dönen JSON verisini sayfadaki ilgili alana yansıtır.

Adım 6: Hata Yönetimi ve Loglama

API servisleri bazen yanıt vermeyebilir veya limitleriniz dolabilir. Bu durumları yönetmek için try-catch bloklarını kullanmak zorunludur.

public function getExchangeRate($from, $to)
{
    try {
        return Cache::remember("rate_{$from}_{$to}", 3600, function () use ($from, $to) {
            $response = Http::timeout(5)->get("https://api.exchangerate-api.com/v4/latest/{$from}");
            if ($response->failed()) throw new \Exception("API Hatası");
            return $response->json()['rates'][$to];
        });
    } catch (\Exception $e) {
        \Log::error("Döviz kuru alınamadı: " . $e->getMessage());
        return null;
    }
}

Bu yöntem, sisteminizin çökmesini engeller ve hatayı Laravel'in storage/logs/laravel.log dosyasına kaydeder.

Finansal Sorumluluk Reddi: Bu makalede anlatılan yöntemler tamamen teknik eğitim amaçlıdır. Döviz kuru verileri anlık piyasa dalgalanmalarına tabidir. Uygulamanızda göstereceğiniz veriler herhangi bir finansal alım-satım garantisi veya yatırım tavsiyesi içermez. Gerçek finansal işlemlerde her zaman resmi banka verilerini kullanın.

Kod Güvenliği Hatırlatması: Kullanıcı girdilerini her zaman doğrulayın (validation). API'den gelen verileri doğrudan veritabanına kaydetmeden önce mutlaka tip dönüşümü (casting) yapın.

Sıkça Sorulan Sorular

API anahtarım çalınırsa ne yapmalıyım?

API sağlayıcınızın paneline giderek anahtarı derhal iptal etmeli ve yeni bir tane oluşturup .env dosyanızı güncellemelisiniz.

Neden Redis kullanmalıyım?

Redis, verileri RAM üzerinde tuttuğu için dosya tabanlı önbelleklemeden çok daha hızlıdır. Yüksek trafikli uygulamalarda Redis kullanımı önerilir.

Para birimi listesini nasıl güncel tutabilirim?

API'nin desteklediği para birimlerini bir veritabanı tablosunda tutabilir ve haftalık bir Scheduled Task (Cron Job) ile güncelleyebilirsiniz.

Dönüştürme işlemi neden bazen hata veriyor?

Genellikle API limitlerinin dolması veya internet bağlantısı sorunları nedeniyle oluşur. Servis sınıfınızda hata yakalama (try-catch) mekanizmasının doğru çalıştığından emin olun.

Bu yöntem e-ticaret siteleri için güvenli mi?

Evet, ancak fiyat hesaplamalarında yuvarlama hatalarından kaçınmak için BCMath kütüphanesini kullanarak hassas matematiksel işlemler yapmanız önerilir.

İleri Düzey İpuçları: BCMath ile Hassas Hesaplama

Finansal uygulamalarda PHP'nin standart float veri tipi, kayan noktalı sayıların ikili sistemdeki temsilinden kaynaklanan hassasiyet hatalarına (precision errors) yol açabilir. Örneğin, 0.1 + 0.2 işlemi beklediğiniz 0.3 sonucunu vermeyebilir. E-ticaret projelerinde bu durum ciddi mali farklara neden olur. Laravel projelerinizde bu sorunu aşmak için BCMath kütüphanesini kullanmalısınız.

Aşağıdaki örnekte, API'den gelen döviz kuru ile ürün fiyatını çarpmak için BCMath kullanımını görebilirsiniz:

public function convertPrice(string $amount, string $rate): string
{
    // scale: 2 basamaklı hassasiyet (kuruluşlar için)
    // bcmath kütüphanesi sayıları string olarak işler
    return bcsub(bcmul($amount, $rate, 4), '0', 2);
}

// Kullanım:
$price = '150.50';
$rate = '32.4512';
$total = $this->convertPrice($price, $rate); // "4883.91"

Dönüştürme İşlemleri İçin Birim Testi Yazma

Döviz kuru gibi dışa bağımlı servislerin kararlılığını test etmek için Mocking yöntemini kullanmalısınız. Servis sınıfınızı doğrudan gerçek API'ye bağlamak yerine, test ortamında sahte yanıtlar dönen bir yapı kurgulamak, testlerinizin hızlı ve güvenilir olmasını sağlar.

Laravel'in Http::fake() metodunu kullanarak servisinizin farklı senaryolara nasıl tepki verdiğini doğrulayabilirsiniz:

public function test_currency_conversion_returns_correct_value()
{
    Http::fake([
        'api.exchangerates.com/*' => Http::response([
            'rates' => ['EUR' => 0.92]
        ], 200)
    ]);

    $service = new CurrencyConverterService();
    $result = $service->convert(100, 'USD', 'EUR');

    $this->assertEquals(92.00, $result);
}

Test Senaryolarında Dikkat Edilmesi Gerekenler

• API Kesintisi: Servisinizin API yanıt vermediğinde varsayılan (fallback) değerleri döndürüp döndürmediğini test edin.
• Geçersiz Para Birimi: Desteklenmeyen bir para birimi kodu girildiğinde sistemin InvalidArgumentException fırlatıp fırlatmadığını kontrol edin.
• Hız Testi: Önbellek (cache) aktifken API'ye tekrar istek atılmadığından emin olmak için Http::assertSentCount(0) kontrolü yapın.

Deployment ve Ölçeklendirme Stratejileri

Uygulamanızı canlıya alırken, döviz kurlarının güncellenme sıklığına göre bir Cron Job stratejisi belirlemelisiniz. Eğer çok yoğun trafik alan bir siteniz varsa, kurları her istekte API'den çekmek yerine, arka planda çalışan bir Scheduled Task ile saatlik olarak Redis üzerinde güncellemek sistem yükünüzü ciddi oranda düşürecektir.

app/Console/Kernel.php dosyanızda şu yapıyı kullanabilirsiniz:

protected function schedule(Schedule $schedule)
{
    // Kurları her saat başı güncelle
    $schedule->job(new UpdateCurrencyRatesJob())->hourly();
}

Bu yaklaşım, kullanıcılarınızın her zaman güncel kurları anlık olarak görmesini sağlarken, API maliyetlerinizi minimize eder ve uygulamanızın yanıt süresini (latency) milisaniyelere indirir.

Sonuç

Laravel ile dinamik bir çoklu para birimi dönüştürücü oluşturmak, hem mimari bilginizi hem de API entegrasyon yeteneklerinizi geliştiren harika bir projedir. Önbellekleme, hata yönetimi ve güvenli konfigürasyon gibi adımları takip ederek profesyonel bir yapı kurdunuz. Bir sonraki adım olarak, kullanıcıların yerel para birimini otomatik olarak tespit eden bir Middleware yazarak kullanıcı deneyimini bir üst seviyeye taşıyabilirsiniz.