MultiCarbon: PHP Carbon için Yerel Jalali ve Hicri Takvim Desteği

İran, Afganistan veya Arapça konuşan ülkelerdeki kullanıcılara yönelik bir projede çalıştıysanız, Jalali (Solar Hijri), Hijri (İslami Ay Takvimi) ve Gregoryen takvimleri arasında tarih dönüştürmenin zorluğunu bilirsiniz.

Bunu kalıcı olarak çözmek için MultiCarbon kütüphanesini geliştirdim; bu bir wrapper değil, doğrudan nesbot/carbon kütüphanesinin bir uzantısı. Zaten bildiğiniz tüm Carbon yöntemleri, herhangi bir takvim modunda sorunsuz bir şekilde çalışır.

## Kurulum

composer require hpakdaman/multicarbon

Bu kütüphane PHP 8.1+ ve Carbon 3 gerektirir.

Temel Prensipler — Tek Bir Zaman Damgası, Üç Takvim

Ana fikir basit: altındaki zaman damgası asla değişmez. Sadece görselleştirme katmanını değiştirirsiniz.

use MultiCarbon\MultiCarbon;

$date = new MultiCarbon(‘2025-03-21’);

echo $date->jalali()->format(‘l j F Y’);
// جمعه 1 فروردین 1404

echo $date->hijri()->format(‘l j F Y’);
// الجمعة 21 رمضان 1446

echo $date->gregorian()->format(‘l j F Y’);
// Friday 21 March 2025

Hepsi bu kadar. Aynı nesne, üç takvim, tamamen akıcı.

Herhangi Bir Takvimde Tarih Oluşturma

Zihinsel dönüşüme gerek yok. Gerekli olan takvimi düşünün:

// Nowruz (Persian New Year)
$nowruz = MultiCarbon::createJalali(1404, 1, 1);
echo $nowruz->gregorian()->format(‘Y-m-d’); // 2025-03-21

// İlk Ramazan Günü
$ramadan = MultiCarbon::createHijri(1446, 9, 1);
echo $ramadan->gregorian()->format(‘Y-m-d’); // 2025-03-01

Takvim Farkındalığına Sahip Hesaplamalar

Burada ilginçleşiyor. Jalali’de bir ay eklemek, Gregoryen’e bir ay eklemekle aynı değil — ay uzunlukları farklıdır. MultiCarbon bunu otomatik olarak yönetir:

// Shahrivar 31 gün, Mehr 30 gün
$date = MultiCarbon::createJalali(1404, 6, 31);
$date->addMonth();
echo $date->format(‘Y/m/d’); // 1404/07/30 — Mehr’in maksimumuna sıkıştırılmış

// Artık yıl yönetimi
$date = MultiCarbon::createJalali(1403, 12, 30); // Esfand 30 (1403 artık yıl)
$date->addYear();
echo $date->format(‘Y/m/d’); // 1404/12/29 — sıkıştırılmış (1404 artık yıl değil)

Yerelleştirilmiş İsimler — Farsça ve Arapça

Ay isimleri, hafta günü isimleri ve hatta AM/PM tamamen yerelleştirilmiştir:

$date = MultiCarbon::createJalali(1404, 3, 15);

echo $date->jalali()->monthName; // خرداد
echo $date->jalali()->dayName; // پنجشنبه

echo $date->hijri()->monthName; // ذیحجه
echo $date->hijri()->dayName; // الخمیس

Farsça, Arapça & Latin Rakamlar

Rakamsal sisteminizi tek bir satırla global olarak değiştirebilirsiniz:

MultiCarbon::setDigitsType(MultiCarbon::DIGITS_FARSI);
echo MultiCarbon::createJalali(1404, 1, 1)->format(‘Y/m/d’);
// ۱۴۰۴/۰۱/۰۱

MultiCarbon::setDigitsType(MultiCarbon::DIGITS_ARABIC);
echo MultiCarbon::createHijri(1446, 9, 1)->format(‘Y/m/d’);
// ١٤٤٦/٠٩/٠١

MultiCarbon::setDigitsType(MultiCarbon::DIGITS_LATIN); // sıfırlama

diffForHumans() Farsça ve Arapça

echo MultiCarbon::createJalali(1403, 1, 1)->diffForHumans();
// 1 سال پیش

echo MultiCarbon::createHijri(1445, 1, 1)->diffForHumans();
// منذ 1 سنة

Takvim Farkındalığına Sahip Sınırlar

Ay ve yıl başlangıcı/bitişi, aktif takvime saygı gösterir:

$date = MultiCarbon::createJalali(1404, 6, 15, 14, 30, 0);

echo $date->copy()->startOfMonth()->format(‘Y/m/d H:i:s’);
// 1404/06/01 00:00:00

echo $date->copy()->endOfMonth()->format(‘Y/m/d H:i:s’);
// 1404/06/31 23:59:59

echo $date->copy()->endOfYear()->format(‘Y/m/d H:i:s’);
// 1404/12/29 23:59:59 (artık yıl değil)

Artık Yıl Tespiti

MultiCarbon::createJalali(1403, 1, 1)->isLeapYear(); // true
MultiCarbon::createJalali(1404, 1, 1)->isLeapYear(); // false

Karşılaştırmalar & Farklar

Tüm karşılaştırma yöntemleri aktif takvimde çalışır:

$a = MultiCarbon::createJalali(1404, 1, 1);
$b = MultiCarbon::createJalali(1404, 1, 25);

$a->isSameMonth($b); // true
$a->isSameDay($b); // false
$a->lessThan($b); // true
$a->diffInDays($b); // 24

Carbon’dan Dönüştürme

Projenizde zaten Carbon kullanıyorsanız, kesintisiz bir şekilde dönüştürülebilir:

$carbon = \Carbon\Carbon::parse(‘2025-03-21’);
$mc = MultiCarbon::fromCarbon($carbon);

echo $mc->jalali()->format(‘Y/m/d’); // 1404/01/01
echo $mc->hijri()->format(‘Y/m/d’); // 1446/09/21

Takvim Özellikleri

Aktif takvimde tüm tarih bileşenlerine erişim:

$date = MultiCarbon::createJalali(1404, 6, 15);

$date->year; // 1404
$date->month; // 6
$date->day; // 15
$date->dayOfYear; // 170
$date->daysInMonth; // 31
$date->quarter; // 2
$date->weekOfYear; // 36
$date->isWeekend(); // false (İran haftası: Cuma hafta sonu)

Serileştirme

$date = MultiCarbon::createJalali(1404, 7, 10, 8, 30, 0);

$date->toDateString(); // “1404-07-10”
$date->toArray();
// [‘year’ => 1404, ‘month’ => 7, ‘day’ => 10, ‘hour’ => 8, ‘minute’ => 30, ‘second’ => 0]

echo $date; // “1404/07/10 08:30:00”

Laravel Entegrasyonu

MultiCarbon, bir Laravel servis sağlayıcısı, facade ve Blade direktifleri ile birlikte gelir:

// Küresel yardımcılar
jdate(‘Y/m/d H:i:s’); // Şu anki Jalali tarihi
hdate(‘Y/m/d’); // Şu anki Hijri tarihi

// Blade direktifleri
@jdate(‘Y/m/d H:i:s’) // Şu anki Jalali
@hdate(‘Y/m/d’) // Şu anki Hijri
@jalali($user->created_at, ‘Y/m/d’) // Jalali’ye dönüştür
@hijri($post->published_at, ‘Y/m/d’) // Hijri’ye dönüştür

Arkada Nasıl Çalışıyor

MultiCarbon, debug_backtrace() kullanarak bir özelliğin veya metodun kodunuza mı yoksa Carbon’un iç motoruna mı erişildiğini tespit eder. Bu demektir ki:

• $date->year çağrıldığında → Jalali/Hijri yılı döner
• Carbon içten $this->year çağrıldığında → Gregoryen döner, böylece ebeveyn mantığı kırılmaz

Bağlantılar:

Geri bildirimlerinizi, önerilerinizi veya özellik taleplerinizi duymak isterim. Sorun açmaktan veya aşağıda bir yorum bırakmaktan çekinmeyin!