Laravel İçin Akıcı Bir Numberable API Geliştirdim: Sayısal Veri Yönetiminde Yeni Bir Dönem (v1.0.0)

Laravel İçin Akıcı Bir Numberable API Geliştirdim: Sayısal Veri Yönetiminde Yeni Bir Dönem (v1.0.0)

Laravel geliştiricileri olarak, projelerimizde sıkça sayısal verilerle çalışırız. Fiyat hesaplamaları, istatistiksel analizler, oranlamalar ve daha birçok senaryoda sayılar hayatımızın vazgeçilmez bir parçasıdır. Ancak, bu sayısal işlemleri yönetirken kodun okunabilirliğini, bakımını ve hata potansiyelini düşündüğümüzde, mevcut yaklaşımların bazen yetersiz kaldığını fark ettim. İşte tam da bu noktada, Laravel ekosistemine yeni bir soluk getireceğine inandığım, akıcı bir Numberable API geliştirdim. Bu makalede, v1.0.0 sürümüyle birlikte gelen bu API’nin ne olduğunu, neden ihtiyaç duyulduğunu, temel özelliklerini ve nasıl kullanılacağını detaylı bir şekilde inceleyeceğiz.

Nedir bu Numberable API?

Numberable API, temel olarak sayısal değerleri sarmalayan (wrap eden) ve bu değerler üzerinde bir dizi akıcı (fluent) metod zinciriyle işlem yapmayı sağlayan bir PHP sınıfıdır. Laravel’in Illuminate\Support\Stringable veya Illuminate\Support\Collection sınıflarına benzer bir mantıkla çalışır; yani, bir sayısal değeri bir nesneye dönüştürerek, üzerinde zincirleme metotlar aracılığıyla karmaşık matematiksel ve formatlama işlemlerini kolayca gerçekleştirmenize olanak tanır.

Temel Tanım ve Amacı

Numberable API’nin temel amacı, PHP’nin yerleşik matematiksel fonksiyonlarının veya doğrudan operatör kullanımlarının getirdiği okunabilirlik ve bakım zorluklarını ortadan kaldırmaktır. Bir sayıyı Number nesnesi içine alarak, add(), subtract(), multiply(), divide(), round(), format() gibi açıklayıcı metotlarla işlem yapmanızı sağlar. Bu, özellikle karmaşık hesaplamaların olduğu yerlerde kodunuzu çok daha anlaşılır ve yönetilebilir hale getirir.

Geleneksel Yaklaşımlar ve Zorlukları

Geleneksel olarak, Laravel projelerinde sayısal işlemler genellikle doğrudan PHP operatörleri veya bcmath, gmp gibi eklentilerle yapılır. Örneğin:

$price = 100.50;
$quantity = 3;
$discount = 0.15;

$total = ($price * $quantity) * (1 - $discount); // Karmaşık ve okunması zor
$taxRate = 0.18;
$finalPrice = round($total * (1 + $taxRate), 2); // Zincirleme yok, her adım ayrı

Bu tür yaklaşımlar, basit işlemler için yeterli olsa da, daha karmaşık senaryolarda (örneğin, birden fazla yuvarlama, formatlama, karşılaştırma ve koşullu işlem) kodun hızla içinden çıkılmaz bir hale gelmesine neden olabilir. Ayrıca, farklı sayı tipleri (integer, float) arasındaki dönüşümler veya hassasiyet sorunları da ek zorluklar yaratır.

Akıcı Arayüzün Farkı

Numberable API, bu zorlukları akıcı bir arayüzle aşar. Her metot, işlem sonucunu yeni bir Number nesnesi olarak döndürdüğü için, istediğiniz kadar işlemi art arda zincirleyebilirsiniz. Bu, kodunuzu daha deklaratif, okunabilir ve "insan diline" yakın hale getirir.

use App\Support\Number; // Varsayımsal bir kullanım

$price = Number::make(100.50);
$quantity = Number::make(3);
$discount = Number::make(0.15);

$total = $price->multiply($quantity)->subtractPercentage($discount); // Daha okunabilir
$taxRate = Number::make(0.18);
$finalPrice = $total->addPercentage($taxRate)->round(2)->get(); // Akıcı zincirleme

Bu örnekte gördüğünüz gibi, işlemlerin sırası ve amacı çok daha net bir şekilde ifade edilmiştir.

Neden Böyle Bir API'ye İhtiyaç Duyuldu?

Numberable API'nin geliştirilmesinin arkasında yatan temel motivasyon, Laravel geliştiricilerinin günlük iş akışlarını iyileştirmek ve sayısal verilerle çalışırken karşılaştıkları yaygın sorunlara zarif bir çözüm sunmaktır.

Kod Okunabilirliği ve Bakım Kolaylığı

En büyük avantajlardan biri, kodun okunabilirliğindeki artıştır. Number::make(10)->add(5)->multiply(2)->divide(3)->round(0)->get() gibi bir ifade, round((10 + 5) * 2 / 3) ifadesinden çok daha sezgiseldir. Her metot, ne yaptığını açıkça belirtir ve bu da yeni bir geliştiricinin kodu anlamasını kolaylaştırır. Bakım açısından da, bir hatayı ayıklamak veya bir hesaplama mantığını değiştirmek, zincirdeki belirli bir metodu bulup değiştirmek kadar basittir.

Tip Güvenliği ve Hata Azaltma

PHP dinamik bir dil olduğu için, bazen değişkenlerin tipini gözden kaçırmak kolay olabilir. Sayısal işlemler sırasında bir string'in veya null değerin araya karışması beklenmedik hatalara yol açabilir. Numberable API, içerideki değeri her zaman bir sayı olarak tutarak bu tür tip güvenliği sorunlarını minimize eder. Ayrıca, özel metotlar sayesinde (örneğin isPositive(), isNegative()), koşullu kontrolleri daha güvenli bir şekilde yapabilirsiniz.

Tekrar Eden İşlemlerden Kurtulma

Birçok projede, belirli sayısal formatlama veya hesaplama kalıpları tekrar eder. Örneğin, her zaman iki ondalık basamağa yuvarlamak veya belirli bir para birimi formatında çıktı almak. Numberable API, bu tür tekrar eden mantığı bir kez yazıp bir metot olarak kullanmanızı sağlar. Hatta, Laravel'in makro özelliği sayesinde kendi özel metotlarınızı kolayca ekleyebilirsiniz, bu da kod tekrarını önemli ölçüde azaltır.

Temel Özellikler ve Avantajlar

Numberable API, geniş bir yelpazede sayısal işlem yetenekleri sunar. İşte bazı öne çıkan özellikler ve sağladığı avantajlar:

Matematiksel İşlemler

API, temel matematiksel işlemleri akıcı bir şekilde gerçekleştirmenizi sağlar:

• add(value): Sayıya değer ekler.
• subtract(value): Sayıdan değer çıkarır.
• multiply(value): Sayıyı değerle çarpar.
• divide(value): Sayıyı değere böler.
• mod(value): Modülüs (kalan) işlemini yapar.
• power(exponent): Sayının üssünü alır.
• abs(): Sayının mutlak değerini alır.
• negate(): Sayının işaretini tersine çevirir.

use App\Support\Number;

$result = Number::make(100)
                ->add(50)       // 150
                ->multiply(2)   // 300
                ->divide(3)     // 100
                ->negate()      // -100
                ->abs()         // 100
                ->get();        // 100

Formatlama ve Yuvarlama

Sayıları belirli bir formata sokmak veya yuvarlamak, finansal uygulamalarda ve raporlamada kritik öneme sahiptir.

• round(precision, mode): Sayıyı belirli bir hassasiyete yuvarlar. (PHP'nin round() modlarını destekler.)
• floor(): Sayıyı aşağı yuvarlar.
• ceil(): Sayıyı yukarı yuvarlar.
• format(decimals, decimal_separator, thousands_separator): Sayıyı belirli bir formata göre string olarak döndürür.
• toCurrency(currency_symbol, decimals, decimal_separator, thousands_separator): Sayıyı para birimi formatında döndürür.

use App\Support\Number;

$price = Number::make(1234.5678);

echo $price->round(2)->get();              // 1234.57
echo $price->floor()->get();               // 1234
echo $price->format(2, ',', '.')->get();   // 1.234,57
echo $price->toCurrency('€', 2, ',', '.')->get(); // € 1.234,57

Karşılaştırma ve Kontroller

Sayısal değerleri karşılaştırmak veya belirli koşulları kontrol etmek için metotlar:

• equals(value): Değerin mevcut sayıya eşit olup olmadığını kontrol eder.
• greaterThan(value): Mevcut sayının değerden büyük olup olmadığını kontrol eder.
• lessThan(value): Mevcut sayının değerden küçük olup olmadığını kontrol eder.
• isPositive(): Sayının pozitif olup olmadığını kontrol eder.
• isNegative(): Sayının negatif olup olmadığını kontrol eder.
• isZero(): Sayının sıfır olup olmadığını kontrol eder.
• isBetween(min, max): Sayının belirli bir aralıkta olup olmadığını kontrol eder.

use App\Support\Number;

$value = Number::make(10);

if ($value->greaterThan(5)->and($value->lessThan(15))) {
    echo "Sayı 5 ile 15 arasındadır.";
}

if ($value->isPositive()->and($value->equals(10))) {
    echo "Sayı pozitif ve 10'a eşittir.";
}

Zincirleme Metotlar (Method Chaining)

En büyük avantajlardan biri, tüm bu metotların birbirine zincirlenebilmesidir. Bu, karmaşık hesaplamaları tek bir satırda, okunabilir bir şekilde ifade etmenizi sağlar. Her metot, yeni bir Number nesnesi döndürdüğü için, orijinal değeriniz değişmez (immutability).

Nasıl Kullanılır? Kurulum ve İlk Adımlar

Numberable API'yi Laravel projenize dahil etmek ve kullanmaya başlamak oldukça basittir.

Kurulum (Composer)

Öncelikle, Composer aracılığıyla paketi projenize eklemeniz gerekmektedir. (Paket adı varsayımsal olarak your-vendor/numberable olarak belirtilmiştir. Gerçek paket adı yayınlandığında farklılık gösterebilir.)

composer require your-vendor/numberable

Bu komut, paketi projenizin vendor dizinine indirecek ve otomatik yükleme mekanizmasını ayarlayacaktır.

Temel Kullanım Örnekleri

Paket kurulduktan sonra, Number sınıfını kullanarak sayısal işlemlerinize başlayabilirsiniz.

addPercentage($taxRate)   // KDV ekle
                        ->subtractPercentage($discount) // İndirim uygula
                        ->round(2)                  // 2 ondalık basamağa yuvarla
                        ->get();                    // Son değeri al

        // Eğer Numberable API'nizde addPercentage ve subtractPercentage yoksa, şöyle de yapabilirsiniz:
        // $finalPrice = $basePrice
        //                 ->multiply(Number::make(1)->add($taxRate))
        //                 ->multiply(Number::make(1)->subtract($discount))
        //                 ->round(2)
        //                 ->get();

        return view('product.show', ['price' => $finalPrice]);
    }
}

make() statik metodu, bir sayısal değeri Number nesnesine dönüştürmek için kullanılır. İşlemler bittikten sonra, get() metodu ile nihai sayısal değere ulaşabilirsiniz.

Farklı Sayı Tipleriyle Çalışma

Numberable API, int, float ve hatta sayısal olarak yorumlanabilecek string değerleri ile sorunsuz bir şekilde çalışabilir. Dahili olarak, hassasiyet gerektiren durumlarda bcmath veya benzeri kütüphaneleri kullanarak doğru sonuçlar elde etmeyi hedefler.

use App\Support\Number;

$integer = Number::make(10);
$float = Number::make(10.5);
$string = Number::make("20.75");

$sum = $integer->add($float)->add($string)->get(); // 10 + 10.5 + 20.75 = 41.25

Gelişmiş Kullanım ve Özelleştirme

Numberable API, sadece temel işlemlerle sınırlı kalmayıp, projenizin özel ihtiyaçlarına göre genişletilebilir ve özelleştirilebilir.

Makrolar ile Genişletme

Laravel'in güçlü makro özelliği sayesinde, Number sınıfına kendi özel metotlarınızı ekleyebilirsiniz. Bu, projenize özgü, sık kullanılan karmaşık hesaplama mantıklarını tek bir metot altında toplayarak kod tekrarını önlemenizi sağlar.
Örneğin, bir ürünün KDV dahil fiyatını hesaplayan bir makro ekleyelim:

// AppServiceProvider.php içinde veya ayrı bir servis sağlayıcıda
use App\Support\Number;
use Illuminate\Support\Str;

public function boot()
{
    Number::macro('addVat', function (float $vatRate = 0.18) {
        // 'this' anahtar kelimesi Number nesnesini temsil eder
        return $this->multiply(1 + $vatRate);
    });

    Number::macro('toWords', function () {
        // Sayıyı yazıya çeviren karmaşık bir mantık varsayalım
        // Bu örnekte sadece basit bir placeholder kullanılmıştır.
        return Str::title($this->get() . " TL");
    });
}

Artık bu makroları doğrudan Number nesnesi üzerinde kullanabilirsiniz:

use App\Support\Number;

$price = Number::make(100);
echo $price->addVat(0.20)->round(2)->get(); // 120.00
echo $price->addVat()->toWords()->get(); // Yüz On Sekiz Tl (varsayımsal)

Özel Formatlama Seçenekleri

format() metodu, ondalık ayırıcı, binlik ayırıcı ve ondalık basamak sayısı gibi parametrelerle esnek formatlama seçenekleri sunar. Bu, farklı bölgesel formatlara veya özel raporlama gereksinimlerine uyum sağlamanıza olanak tanır.

use App\Support\Number;

$value = Number::make(1234567.8912);

echo $value->format(2, '.', ',')->get(); // 1,234,567.89 (ABD formatı)
echo $value->format(2, ',', '.')->get(); // 1.234.567,89 (TR formatı)

Laravel Ekosistemiyle Entegrasyon

Numberable API, Laravel'in diğer bileşenleriyle de kolayca entegre edilebilir. Örneğin, Eloquent modellerinizdeki accessor'lar veya mutator'lar aracılığıyla veritabanından gelen sayısal verileri otomatik olarak Number nesnelerine dönüştürebilir veya kaydetmeden önce formatlayabilirsiniz.

// App\Models\Product.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Support\Number;

class Product extends Model
{
    // ...

    public function getPriceAttribute($value)
    {
        return Number::make($value);
    }

    public function setPriceAttribute($value)
    {
        // Eğer Number nesnesi geliyorsa get() ile değeri al
        $this->attributes['price'] = $value instanceof Number ? $value->get() : $value;
    }
}

// Kullanım
$product = Product::find(1);
$newPrice = $product->price->add(10)->round(2)->get(); // price artık bir Number nesnesi
$product->price = $newPrice;
$product->save();

Perde Arkası: Tasarım Prensipleri

Numberable API'yi geliştirirken, sadece işlevsellik değil, aynı zamanda sağlam bir mimari ve iyi tasarım prensipleri de göz önünde bulunduruldu.

Immutability (Değişmezlik)

Numberable API'nin temel tasarım prensiplerinden biri değişmezliktir (immutability). Bir Number nesnesi oluşturulduktan sonra, üzerinde yapılan hiçbir işlem orijinal nesnenin değerini değiştirmez. Bunun yerine, her metot, yapılan işlemin sonucunu içeren *yeni bir Number nesnesi* döndürür. Bu yaklaşımın birçok avantajı vardır:

• Öngörülebilirlik: Kodunuzun her zaman beklenen şekilde davranmasını sağlar, yan etkileri ortadan kaldırır.
• Güvenilirlik: Birden fazla yerde aynı Number nesnesini kullanırken, bir yerdeki değişikliğin başka bir yeri etkileme riski ortadan kalkar.
• Hata Ayıklama Kolaylığı: Her adımda yeni bir nesne döndüğü için, bir hatanın nerede meydana geldiğini izlemek daha kolaydır.

Akıcı Arayüz Tasarımı

API'nin "akıcı" olması, metot zincirleme yeteneği anlamına gelir. Bu, her metodun kendisini ($this) döndürmesiyle sağlanır. Bu tasarım deseni, kodun daha doğal, okunabilir ve "hikaye anlatır" gibi olmasını sağlar. Laravel'in Collection ve Stringable sınıfları da aynı deseni kullanır, bu da Numberable API'nin Laravel ekosistemine doğal bir şekilde uyum sağlamasına yardımcı olur.

Performans ve Optimizasyon

Sayısal işlemlerin performansı, özellikle büyük veri kümeleriyle çalışırken kritik olabilir. Numberable API, dahili olarak PHP'nin yerleşik sayısal tiplerini kullanır ve gerektiğinde bcmath gibi hassas matematik kütüphanelerinden faydalanır. Amaç, hem doğruluktan ödün vermemek hem de gereksiz yere performans düşüşüne yol açmamaktır. Çoğu durumda, bir Number nesnesi kullanmanın doğrudan PHP operatörlerini kullanmaya göre ihmal edilebilir bir performans farkı yaratması beklenir. Ancak, performansın kritik olduğu ve milyonlarca işlem yapılan senaryolarda, doğrudan operatör kullanımı hala en hızlı yol olabilir. Bu tür durumlarda, Numberable API'nin sağladığı okunabilirlik ve bakım kolaylığı ile performans arasındaki dengeyi değerlendirmek önemlidir.

Gelecek Planları ve Topluluk

Numberable API'nin v1.0.0 sürümü, sağlam bir temel sunsa da, gelecekteki geliştirmeler için birçok potansiyel barındırıyor.

Yaklaşan Özellikler

Gelecek sürümlerde eklenmesi planlanan bazı özellikler şunlardır:

• Para Birimi Yönetimi: Farklı para birimleri arasında dönüşüm, kur hesaplamaları ve para birimine özel formatlama.
• İstatistiksel Fonksiyonlar: Ortalama, medyan, standart sapma gibi temel istatistiksel hesaplamalar.
• Daha Gelişmiş Matematiksel Fonksiyonlar: Logaritma, trigonometrik fonksiyonlar gibi daha karmaşık matematiksel işlemler.
• Uluslararasılaştırma (i18n) Desteği: NumberFormatter gibi PHP'nin yerleşik araçlarını kullanarak daha esnek uluslararası sayı formatlama.
• JSON Serileştirme: Number nesnelerinin doğrudan JSON'a serileştirilebilmesi.

Katkıda Bulunma Yolları

Bu proje, açık kaynak topluluğunun gücüne inanarak geliştirilmiştir. Geliştirmelere katkıda bulunmak isteyen herkesi GitHub deposuna bekliyorum. Hata raporları, yeni özellik önerileri, dokümantasyon iyileştirmeleri veya doğrudan kod katkıları, projenin daha iyiye gitmesi için çok değerlidir. Projenin GitHub linkini yakında duyuracağım.

Geri Bildirim ve Destek

Numberable API'yi kullanan geliştiricilerden gelecek her türlü geri bildirim çok kıymetlidir. Karşılaştığınız sorunlar, beğendiğiniz veya beğenmediğiniz yönler, eksik bulduğunuz özellikler veya iyileştirme önerileri için lütfen benimle iletişime geçmekten çekinmeyin. Geri bildirimleriniz, API'nin gelecekteki yol haritasını şekillendirmede önemli bir rol oynayacaktır.

Sonuç

Laravel için geliştirdiğim bu akıcı Numberable API (v1.0.0), sayısal verilerle çalışmayı daha keyifli, güvenli ve verimli hale getirmeyi hedefliyor. Kod okunabilirliğini artırması, bakım maliyetlerini düşürmesi ve hata potansiyelini azaltmasıyla, özellikle finans, e-ticaret ve raporlama gibi sayısal işlemlerin yoğun olduğu projelerde geliştiricilere büyük kolaylıklar sağlayacaktır. Laravel'in akıcı arayüz geleneğini sayısal dünyaya taşıyan bu paket, modern PHP uygulamalarında sayısal veri yönetiminde yeni bir standart belirlemeye adaydır. Projelerinizde deneyerek geri bildirimlerinizi paylaşmanızı dört gözle bekliyorum!

SSS (Sık Sorulan Sorular)

S1: Neden doğrudan PHP'nin matematik fonksiyonlarını kullanmıyorum?

Doğrudan PHP fonksiyonları basit işlemler için yeterli olsa da, Numberable API daha karmaşık, zincirleme işlemlerde kod okunabilirliğini ve bakım kolaylığını artırır. Ayrıca, tip güvenliği ve hata azaltma konusunda ek avantajlar sunar. Her metot, ne yaptığını açıkça belirttiği için kodunuz daha sezgisel hale gelir.

S2: Performans etkisi var mı?

Evet, her nesne oluşturma ve metot çağrısı, doğrudan operatör kullanımına göre küçük bir performans yükü getirir. Ancak, modern PHP yorumlayıcıları ve Numberable API'nin optimize edilmiş yapısı sayesinde, bu fark çoğu uygulama için ihmal edilebilir düzeydedir. Performansın milisaniyelerle ölçüldüğü ve milyonlarca işlemin yapıldığı çok yoğun senaryolarda, doğrudan operatör kullanımı hala tercih edilebilir.

S3: Hangi sayı tiplerini destekliyor?

Numberable API, PHP'nin int, float ve sayısal olarak yorumlanabilen string tiplerini destekler. Dahili olarak, hassasiyet gerektiren durumlarda bcmath gibi kütüphanelerden faydalanarak doğru sonuçlar elde etmeyi amaçlar.

S4: Laravel dışında kullanabilir miyim?

Evet, Numberable API Laravel'den bağımsız bir PHP paketidir. Herhangi bir PHP projesinde Composer aracılığıyla kurup kullanabilirsiniz. Laravel'in makro özelliği gibi bazı entegrasyonlar Laravel'e özgü olsa da, temel işlevsellik tüm PHP projelerinde mevcuttur.

S5: Nereden katkıda bulunabilirim veya destek alabilirim?

Projenin GitHub deposu üzerinden hata raporları açabilir, yeni özellik önerilerinde bulunabilir veya doğrudan kod katkısı sağlayabilirsiniz. Ayrıca, geri bildirimleriniz ve sorularınız için benimle doğrudan iletişime geçebilirsiniz. GitHub linki ve iletişim kanalları yakında duyurulacaktır.