📝 Orijinal yayım unfoldcms.com‘da yapılmıştır — DEV topluluğu için burada yeniden yayımlanmaktadır. (UnfoldCMS üzerinde çalışıyorum.)
<p>Pek çok tarih kütüphanesi bir tercih yapmanızı gerektirir. Ya mükemmel bir API'ye sahip olursunuz ancak sadece bir takvimle sınırlı kalırsınız ya da bir Pers takvimini bir sarmalayıcı olarak eklediğinizde Carbon’un sunduğu birçok özellikten feragat edersiniz. Uygulamanız İran, Afganistan veya Körfez'deki kullanıcılara hizmet veriyorsa, bir gün size Hem Jalali hem de Gregoryen tarih istenildiğinde bu durum sıkıntı yaratacaktır.</p>
<p><strong>Özetle:</strong> <a href="https://carbon.nesbot.com/" target="_blank" rel="noopener noreferrer">Carbon</a>, PHP'deki standart tarih kütüphanesidir, ancak yalnızca Gregoryen takvimi ile çalışmaktadır. MultiCarbon, açık kaynak kodlu küçük bir pakettir ve doğrudan Carbon'u uzatarak Jalali (Güneş Hijri) ve Hijri (İslami Ay) takvimlerini ekler — böylece <code>format()</code>, <code>addMonths()</code>, <code>diffForHumans()</code> gibi metodlar çalışmaya devam eder, sadece istediğiniz takvimde. Bu yazı, onu gerçek bir Laravel uygulamasında nasıl kullanacağınızı gösterirken, bugünden itibaren yapıştırabileceğiniz kodlar sunmaktadır.</p>
<p>MIT lisansı ile yayınlanmış ve <a href="https://unfoldcms.com/" target="_blank" rel="noopener noreferrer">UnfoldCMS</a> projesinin bir parçası olarak geliştirilmiştir. Tam açıklama: UnfoldCMS üzerinde çalışıyorum ve MultiCarbon'u kendimiz için gerektiği için açık kaynak yaptık.</p>
<hr/>
<h2>
<a name="the-problem-carbon-only-knows-one-calendar" href="#the-problem-carbon-only-knows-one-calendar"></a>
Sorun: Carbon Yalnızca Bir Takvim Biliyor
</h2>
<p>Carbon mükemmeldir. Zaman dilimlerini, farklı tarihleri, değişmeyen nesneleri, serileştirmeyi yönetir ve Laravel içine derinlemesine entegre edilmiştir — <code>$user->created_at</code> kutudan çıkar çıkmaz bir Carbon nesnesidir. Ancak, Carbon yalnızca Gregoryen takvimini desteklemektedir.</p>
<p>Eğer bir Pers (Jalali) tarihi gerekiyorsa, bugüne kadar iki kötü seçenek vardı:</p>
<ol>
<li>
<strong>Ayrı bir Jalali kütüphanesi</strong> — çalışır, ancak ayrı bir nesne türüdür. Carbon’un zaman dilimi yönetimini, tarih farkını, Laravel dönüşümlerini kaybedersiniz. Artık kodunuzun her yerinde dönüştürme yapmanız gerekir.
</li>
<li>
<strong>İnce bir sarmalayıcı</strong> — biraz daha iyi, ancak çoğu sarmalayıcı Carbon'un yüzeyinin yalnızca bir kısmını yeniden uygular. Unutulan bir metodu çağırdığınızda, sorununuz başlar.
</li>
</ol>
<p>Her iki yol da aynı şekilde sona erer: bir uygulamada tarihler için iki zihinsel modele sahip olursunuz. İşte sorun burada başlar.</p>
<hr/>
<h2>
<a name="what-multicarbon-does-differently" href="#what-multicarbon-does-differently"></a>
MultiCarbon'un Farkı
</h2>
<p>MultiCarbon, <strong><code>Carbon\Carbon</code>'ı genişleterek</strong> inşa edilmiştir. Bu tasarım tercihi her şeyi değiştirir. Çünkü bir <code>MultiCarbon</code> nesnesi <em>bir</em> Carbon nesnesidir, bu nedenle her Carbon metodunu kullanır — sadece aktif takvimi herhangi bir nesnede değiştirebilme yeteneğine sahip olursunuz.</p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="kn">use</span> <span class="nc">MultiCarbon\MultiCarbon</span><span class="p">;</span>
// Jalali takvimde bir tarih oluştur
$date = MultiCarbon::createJalali(1404, 1, 1); // Nowruz 1404
echo $date->format(‘Y/m/d’); // “1404/01/01”
echo $date->format(<span class=”s1>’l j F Y’); // “جمعه 1 فروردین 1404”
// Aynı nesne, farklı takvim — zaman damgası değişmiyor
echo $date->hijri()->format(<span class=”s1>’Y/m/d’); // “1446/08/21”
echo $date->gregorian()->format(<span class=”s1>’Y/m/d’); // “2025/03/21”
<p>Temel Unix zaman damgası sabit kalır. <code>->jalali()</code>, <code>->hijri()</code> ve <code>->gregorian()</code> yalnızca tarihlerin <em>okunma ve görüntülenme şeklini</em> değiştirir — zamanı değiştirmez. İşte bu trick, diğerlerinin de bozulmamasını sağlar.</p>
<h3>
<a name="its-still-just-carbon" href="#its-still-just-carbon"></a>
Hala Sadece Carbon
</h3>
<p>Gerçek bir kod tabanı için önemli olan kısmı burada. Zaten kullandığınız her Carbon metodu, Jalali veya Hijri modunda çalışmaya devam eder:</p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="nv">$date</span> <span class="o">=</span> <span class="nc">MultiCarbon</span><span class="o">::</span><span class="nf">createJalali</span><span class="p">(</span><span class="mi">1404</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">14</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
$date->addDays(10); // Carbon native
$date->addMonths(2); // takvime duyarlı (2 Jalali ay)
$date->isPast(); // true / false
$date->isWeekend(); // Cuma tespiti (İran haftası)
$date->diffForHumans(); // “۳ ماه پیش” — yerelleştirilmiş Farsça
$date->getTimestamp(); // doğru Unix zaman damgası
$date->timezone(<span class=”s1>’Asia/Tehran’); // tam zaman dilimi desteği
$date->copy()->startOfMonth(); // 1404/06/01 00:00:00
// Herhangi bir Carbon bekleyen yere verin — çalışır
function logDate(\Carbon\Carbon $d) { / … / }
logDate($date); // MultiCarbon BİR Carbon’dır
<p>Türleri dönüştürmeye gerek yok. İkinci bir zihinsel modele ihtiyacınız yok. Zaten bildiğiniz Carbon ile yazarsınız.</p>
<hr/>
<h2>
<a name="how-to-add-multicalendar-dates-to-a-laravel-app" href="#how-to-add-multicalendar-dates-to-a-laravel-app"></a>
Laravel Uygulamasına Çoklu Takvim Tarihleri Nasıl Eklenir
</h2>
<p>İşte pratik bir yol haritası — yükleme, Jalali tarihlerinin Blade'de görüntülenmesi ve güvenli bir şekilde tarihler depolama.</p>
<h3>
<a name="step-1-install" href="#step-1-install"></a>
Adım 1: Yükleme
</h3>
<div class="highlight js-code-highlight">
<pre class="highlight shell"><code>composer require hpakdaman/multicarbon
<p>Bu, <strong>PHP 8.1+</strong> ve <strong>Carbon 2.x veya 3.x</strong> gerektirir. Laravel'de, hizmet sağlayıcı ve façade otomatik keşfedilir — kaydedilecek bir şey yoktur.</p>
<h3>
<a name="step-2-show-a-jalali-date-in-blade" href="#step-2-show-a-jalali-date-in-blade"></a>
Adım 2: Blade'de Jalali Tarihi Gösterme
</h3>
<p>Paket, depo edilen Gregoryen tarihini bir görünümde Jalali'ye dönüştüren Blade direktifleri ile birlikte gelir:</p>
<div class="highlight js-code-highlight">
<pre class="highlight plaintext"><code>{{-- Depolanan herhangi bir datetime'ı Jalali'ye dönüştür --}}
@jalali($post->published_at, ‘Y/m/d’) {{– 1404/06/15 –}}
{{– Mevcut tarih, Hijri –}}
@hdate(‘Y/m/d’) {{– 1446/08/15 –}}
{{– Tarih ve saat ile mevcut Jalali tarihi –}}
@jdate(‘Y/m/d H:i:s’)
<p>Hiçbir denetleyici değişikliği yok. Hiçbir dönüşüm karmaşası yok. Direktif, geçirdiğiniz her Carbon uyumlu değeri alır ve hedef takvimde görüntüler.</p>
<h3>
<a name="step-3-use-the-global-helpers-anywhere" href="#step-3-use-the-global-helpers-anywhere"></a>
Adım 3: Küresel Yardımcıları Her Yerde Kullanın
</h3>
<p>Blade dışında — işler, komutlar, API kaynaklarında — düz yardımcılar mevcuttur:</p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="nf">jdate</span><span class="p">(</span><span class="s1>'Y/m/d'</span><span class="p">);</span> <span class="c1">// "1404/06/15" — mevcut Jalali tarihi</span>
jdate(<span class=”s1>’Y/m/d’, $timestamp); // Unix zaman damgasından
hdate(<span class=”s1>’Y/m/d’); // “1446/08/15” — mevcut Hijri tarihi
multicarbon(); // zincirleme yapı için bir MultiCarbon nesnesi
<h3>
<a name="step-4-store-gregorian-display-jalali" href="#step-4-store-gregorian-display-jalali"></a>
Adım 4: Gregoryen Olarak Depola, Jalali Olarak Göster
</h3>
<p>Bu, acınızı hafifleten tek kuraldır: <strong>tarihleri veritabanınızda Gregoryen (UTC) olarak depolayın ve yalnızca görüntüleme zamanında dönüştürün.</strong> Veritabanınız düzenli kalır, sorgularınız normal kalır ve takvim tamamen bir sunum meselesi haline gelir.</p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="c1">// Depolama — Laravel'in Gregoryen zaman damgasını normal olarak depolamasına izin verin</span>
$post->published_at = now();
$post->save();
// Gösterme — sınırda dönüştür
echo MultiCarbon::fromCarbon($post->published_at)->jalali()->format(<span class=”s1>’Y/m/d’);
<p>MultiCarbon, Carbon'u genişlettiğinden, <code>fromCarbon()</code> değerini kabul eder. Laravel'in size zaten verdiği değer. Hiçbir göç işlemi ya da şema değişikliği yok.</p>
<hr/>
<h2>
<a name="what-you-actually-get" href="#what-you-actually-get"></a>
Gerçekten Ne Alıyorsunuz
</h2>
<p>Pakette ne olduğunu ve hangi yeteneklerin mevcut olduğunu hızlı bir şekilde gösteren bir liste:</p>
<div class="table-wrapper-paragraph">
<table>
<thead>
<tr>
<th>Yetenek</th>
<th>Nasıl</th>
</tr>
</thead>
<tbody>
<tr>
<td>Üç takvim</td>
<td>
<code>->jalali()</code>, <code>->hijri()</code>, <code>->gregorian()</code> her nesne üzerinde</td>
</tr>
<tr>
<td>Takvime duyarlı hesaplama</td>
<td>
<code>addMonths()</code>, <code>addYears()</code>, <code>startOfMonth()</code>, <code>endOfYear()</code> takvim sınırlarını dikkate alır</td>
</tr>
<tr>
<td>Yerelleştirilmiş çıktı</td>
<td>Farsça + Arapça ay isimleri, hafta günleri, AM/PM, <code>diffForHumans()</code></td>
</tr>
<tr>
<td>Rakamsal görüntü</td>
<td>Latin, Farsça (<code>۱۲۳۴</code>) veya Arap-İndik (<code>١٢٣٤</code>) rakamları</td>
</tr>
<tr>
<td>İran haftası</td>
<td>Cumartesi ilk gün, Cuma hafta sonu</td>
</tr>
<tr>
<td>Laravel entegrasyonu</td>
<td>Otomatik keşif, Facade, Blade direktifleri (<code>@jalali</code>, <code>@hijri</code>, <code>@jdate</code>, <code>@hdate</code>)</td>
</tr>
<tr>
<td>Küresel yardımcılar</td>
<td>
<code>jdate()</code>, <code>hdate()</code>, <code>multicarbon()</code></td>
</tr>
<tr>
<td>Bağımlılıklar</td>
<td>Sadece Carbon'un kendisi dışında hiçbiri yok</td>
</tr>
</tbody>
</table>
</div>
<p>Form ve içe aktarımlar için yararlı bir ayrıntı: kullanıcı tarafından yazılan takvim spesifik bir dizeyi doğrudan ayrıştırabilirsiniz, önce elle dönüştürmek yerine.</p>
<div class="highlight js-code-highlight">
<pre class="highlight php"><code><span class="c1">// Kullanıcının yazdığı bir Jalali tarihi ayrıştır</span>
$mc = MultiCarbon::parseFormat(<span class=”s1>’Y/m/d’, <span class=”s1>’1404/01/15′);
// Bir Hijri tarihi ayrıştır
use MultiCarbon\CalendarMode;
$mc = MultiCarbon::parseFormat(<span class=”s1>’Y/m/d’, <span class=”s1>’1446/07/15′, CalendarMode::HIJRI);
<hr/>
<h2>
<a name="how-does-it-keep-full-carbon-compatibility" href="#how-does-it-keep-full-carbon-compatibility"></a>
Nasıl Tam Carbon Uyumluluğunu Sağlıyor?
</h2>
<p>MultiCarbon, özellik erişimini (<code>year</code>, <code>month</code>, <code>day</code>) ve birkaç anahtar metodu (<code>format()</code>, <code>setDate()</code>, <code>addMonths()</code>) kesiyor ve <em>kim</em> tarafından çağrıldığını kontrol ediyor.</p>
<p>İçsel Carbon üzerinde çalışmaya devam eden kod/uygulama arasında dönüştürmeyi sağlamak için <code>debug_backtrace()</code> kullanır:</p>
<ul>
<li>
<strong>Sizin kodunuz</strong> <code>$date->year</code> okur → aktif takvimdeki yılı geri verir (Jalali veya Hijri).</li>
<li>
<strong>Carbon içsel olarak</strong> <code>$this->year</code> okur → Gregoryen'i geri verir, böylece Carbon’un kendi iç mekanizması doğru bir şekilde çalışmaya devam eder.</li>
</li>
</ul>
<p>Dönüştürme, yalnızca kodunuz ile Carbon arasındaki sınırda gerçekleşir. Onun altında - farklılık, zaman dilimi hesaplamaları, serileştirme - tamamen Gregoryen, dokunulmamış çalışır. İşte bu yüzden hiçbir Carbon davranışını kaybetmezsiniz: kütüphane hiçbir şeyin önüne geçmez.</p>
<hr/>
<h2>
<a name="when-to-reach-for-this" href="#when-to-reach-for-this"></a>
Bunun İçin Ne Zaman Ulaşmalısınız?
</h2>
<p>MultiCarbon'un nerede durduğuna dair birkaç dürüst kılavuz:</p>
<ol>
<li>
<strong>Pers veya Arapça konuşan kullanıcılara hizmet veriyorsanız</strong> ve tarihlerinin takvimde gösterilmesine ihtiyaç duyuyorsanız. Bu, temel durumdur.</li>
<li>
<strong>Zaten Carbon / Laravel üzerinde iseniz</strong> ve ikinci bir tarih tipinin kodunuzu kirletmesini istemiyorsanız. MultiCarbon yeniden yazmalar olmadan entegre edilir.</li>
<li>
<strong>Takvime duyarlı bir matematiğe ihtiyacınız varsa</strong> — "3 Jalali ay ekleyin" "yaklaşık 90 gün ekleyin" ile aynı değildir ve MultiCarbon, ay uzunluğu farklılıklarını sizin için yönetir.</li>
</ol>
<p>Ne zaman <em>bununla uğraşmama</em> gerektiği: Uygulamanız yalnızca Gregoryen ise, buna ihtiyacınız yok - düz Carbon mükemmel. MultiCarbon, birden fazla takvim işin içine girdiğinde yerini alır.</p>
<hr/>
<h2>
<a name="why-we-built-it-and-opensourced-it" href="#why-we-built-it-and-opensourced-it"></a>
Neden Bunu Yaptık (ve Açık Kaynak Hale Getirdik)
</h2>
<p>MultiCarbon, <a href="https://unfoldcms.com/features" target="_blank" rel="noopener noreferrer">UnfoldCMS</a> üzerinde çalışırken ortaya çıktı, farklı yerel ayarlarla içerik yayınlayıp programladığımız kendi kendine barındırılan bir CMS. Jalali ve Hijri tarihlerinin, admin panelinde, API'de veya planlı yayınlamada Carbon tarihlerine tam olarak uyması gerektiğini hissettik — iki tarih sistemini yönetmeden.</p>
<p>Bunu içsel olarak tutmak yerine, aynı sorunu yaşayan herkesin kullanabilmesi için MIT lisansı altında yayınlamaya karar verdik. Eğer bir <a href="https://unfoldcms.com/blog/laravel-cms-vs-wordpress-complete-comparison-2026/" target="_blank" rel="noopener noreferrer">CMS veya Laravel'de bir uygulama geliştiriyorsanız</a> veya <a href="https://unfoldcms.com/blog/unfoldcms-public-api-v1-launch" target="_blank" rel="noopener noreferrer">başsız REST API’mizle</a> çalışıyorsanız, aynı takvim işleme doğrudan size de sunulmaktadır.</p>
<p>Şimdi yükleyebilirsiniz: <code>composer require hpakdaman/multicarbon</code>. Kaynak ve belgeler <a href="https://github.com/hpakdaman/multicarbon" target="_blank" rel="noopener noreferrer">GitHub</a>'da.</p>
<hr/>
<h2>
<a name="frequently-asked-questions" href="#frequently-asked-questions"></a>
Sıkça Sorulan Sorular
</h2>
<h3>
<a name="does-multicarbon-replace-carbon" href="#does-multicarbon-replace-carbon"></a>
MultiCarbon, Carbon'un yerini alır mı?
</h3>
<p>Hayır — Carbon’u genişletir. Bir <code>MultiCarbon</code> nesnesi, <em>bir</em> <code>Carbon</code> nesnesidir, bu nedenle Carbon bekleyen herhangi bir koda verebilir ve Carbon’un tüm metodları çalışır. Carbon ile yan yana eklersiniz, Carbon’u değiştirmezsiniz.</p>
<h3>
<a name="does-it-work-with-carbon-3" href="#does-it-work-with-carbon-3"></a>
Carbon 3 ile çalışır mı?
</h3>
<p>Evet. MultiCarbon, PHP 8.1+ gerektirir ve hem Carbon 2.x hem de 3.x'yi destekler. Projeniz üzerinde hangisi varsa seçin.</p>
<h3>
<a name="will-it-change-how-my-dates-are-stored-in-the-database" href="#will-it-change-how-my-dates-are-stored-in-the-database"></a>
Tarihlerim veritabanında nasıl saklanacak değişir mi?
</h3>
<p>Hayır. Tavsiye edilen model, tarihlerinin Gregoryen (UTC) gibi depolanmasıdır; Laravel zaten bunu yapmaktadır ve yalnızca görüntüleme esnasında Jalali veya Hijri'ye dönüştürülmedir. Hiçbir göç veya şema değişikliği gerektirmez.</p>
<h3>
<a name="does-it-support-hijri-islamic-dates-or-only-jalali" href="#does-it-support-hijri-islamic-dates-or-only-jalali"></a>
Sadece Jalali'yi mi destekliyor yoksa Hijri (İslami) tarihleri de mi var?
</h3>
<p>Her ikisi de. MultiCarbon, Jalali (Güneş Hijri), Hijri (İslami Ay) ve Gregoryen tarihleri yönetir. Herhangi bir nesne üzerinde <code>->jalali()</code>, <code>->hijri()</code>, <code>->gregorian()</code> ile geçiş yapabilirsiniz.</p>
<h3>
<a name="can-i-show-persian-farsi-digits-instead-of-latin-numbers" href="#can-i-show-persian-farsi-digits-instead-of-latin-numbers"></a>
Latin sayılar yerine Farsça (Persian) rakamları gösterebilir miyim?
</h3>
<p>Evet. MultiCarbon, tarihleri Latin (<code>1234</code>), Farsça (<code>۱۲۳۴</code>) veya Arap-İndik (<code>١٢٣٤</code>) rakamlarıyla görüntülemeyi sağlayabilir ve ay isimlerini, hafta isimlerini ve "human için fark" çıktısını yerelleştirir.</p>
<hr/>
<p><em>MultiCarbon, MIT lisansı altında açık kaynaklıdır. Geliştiriciler için bir kendinden barındırılan CMS olan <a href="https://unfoldcms.com/" target="_blank" rel="noopener noreferrer">UnfoldCMS</a> içinde inşa edilir ve sürdürülmektedir. Yükleyin: <code>composer require hpakdaman/multicarbon</code> — kaynak GitHub'da <a href="https://github.com/hpakdaman/multicarbon" target="_blank" rel="noopener noreferrer">burada</a>.</em></p>
<hr/>
<p>💬 <strong>İlk olarak kendi sitemde yayımlandı:</strong> <a href="https://unfoldcms.com/blog/multi-calendar-dates-laravel-jalali-hijri/" target="_blank" rel="noopener noreferrer">https://unfoldcms.com/blog/multi-calendar-dates-laravel-jalali-hijri/</a></p>
<p>UnfoldCMS, geliştiriciler için bir kendinden barındırma, odaklı CMS'dir. Bu konudan herhangi biri faydalıysa — ya da katılmıyorsanız — yorumlarda benimle iletişime geçebilirsiniz.</p>
