Laravel’de Carbon ile Jalali ve Hicri Tarihleri Yönetme (MultiCarbon)

Paylaş

Alıntı: UnfoldCMS’de ilk olarak yayımlanmıştır. (UnfoldCMS’de çalışıyorum.)

<p>Birçok tarih kütüphanesi, bir takvim ile harika bir API sunarken diğer takvimler için yarı performans sunuyor. Uygulamanız İran, Afganistan veya Körfez bölgesindeki kullanıcılara hizmet veriyorsa, bir gün birisi Jalali takvimini Gregoryen takvimle yan yana isterse, bu durum sorun haline gelir.</p>

<p><strong>TL;DR:</strong> <a href="https://carbon.nesbot.com/" target="_blank" rel="noopener noreferrer">Carbon</a>, PHP'de tarihler için standarttır ancak sadece Gregoryen ile çalışır. MultiCarbon, Carbon'ı genişleten küçük bir açık kaynak paketidir; Jalali (Güneş Hijri) ve Hijri (İslami Ay) takvimlerini ekler — böylece <code>format()</code>, <code>addMonths()</code>, <code>diffForHumans()</code> ve Laravel entegrasyonu çalışmaya devam eder, istediğiniz takvimde. Bu yazı, gerçek bir Laravel uygulamasında nasıl kullanılacağını gösterir, bu gün uygulamanıza yapıştırabileceğiniz kodlarla. Bu paket MIT lisansı altındadır ve <a href="https://unfoldcms.com/" target="_blank" rel="noopener noreferrer">UnfoldCMS</a>'in bir parçası olarak oluşturulmuştur.</p>

<hr/>
<h2>
    <a name="the-problem-carbon-only-knows-one-calendar" href="#the-problem-carbon-only-knows-one-calendar"></a>
    Sorun: Carbon Sadece Bir Takvimi Tanır
</h2>

<p>Carbon mükemmel bir kütüphanedir. Zaman dilimlerini yönetir, tarih farkı alır, değişmezlik sağlar ve Laravel'e derin entegre edilir — <code>$user->created_at</code> doğrudan bir Carbon nesnesidir. Sorun, Carbon'un sadece Gregoryen takvimle çalışmasıdır.</p>

<p>Bir Jalali tarihi gereksiniminiz olduğunda, geçmişte iki kötü seçeneğiniz vardı:</p>
<ol>
    <li>
        <strong>Ayrı bir Jalali kütüphanesi</strong> - çalışıyor ancak ayrı bir nesne türüdür. Carbon'un zaman dilimi yönetimi, tarih farkı hesaplama ve Laravel dönüşümleri kaybedilir. Artık kodunuzun her yerinde geri dönüşüm yapmanız gerekir.</li>
    <li>
        <strong>Ince bir sarmalayıcı</strong> - daha yakın, ancak çoğu sarmalayıcı Carbon'un yüzeyinin bir kısmını yeniden uygular. Unuttukları bir yöntemi çağırdığınızda, sistem çöker.</li>
</ol>

<p>İki yolun sonu aynı: bir uygulama içinde tarihler için iki zihinsel model tutarsınız. İşte burada hatalar doğar.</p>

<hr/>
<h2>
    <a name="what-multicarbon-does-differently" href="#what-multicarbon-does-differently"></a>
    MultiCarbon Ne Yapıyor?
</h2>

<p>MultiCarbon <strong>Carbon\Carbon</strong> uzantısı olarak çalışır; bu tasarım kararı her şeyi değiştirir. Çünkü bir <code>MultiCarbon</code> örneği <em>bir</em> Carbon örneğidir, bu nedenle her Carbon metodu çalışır — yalnızca herhangi bir örnekte aktif takvimi değiştirme yeteneği kazanırsınız.</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(<span class=”s1>’Y/m/d’); // “1404/01/01”
echo $date->format(<span class=”s1>’l j F Y’); // “جمعه 1 فروردین 1404”

// Aynı örnek, farklı takvim — zaman damgası sabit kalır
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 tarihi nasıl <em>okur ve gösterir</em> — zaman açısından sabit durur. İşte bu kütüphanenin özelliği ve başka hiçbiri bozulmaz.</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ısım bu. Bugüne kadar 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 için yerel
$date->addMonths(2); // takvim değerli (2 Jalali ay)
$date->isPast(); // doğru / yanlış
$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

// Carbon bekleyen her şeye verin — sadece çalışır
function logDate(\Carbon\Carbon $d) { / … / }
logDate($date); // MultiCarbon, gerçekten Carbon’dır

<p>Tür dönüştürmesi yok. İkinci bir zihinsel model yok. Zaten bildiğiniz Carbon'u yazmaya devam edersiniz.</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 Uygulamanıza Çoklu Takvim Tarihleri Eklemek
</h2>

<p>İşte pratik bir rehber — kurulumu yapın, Blade'de Jalali tarihleri gösterin ve tarihleri güvenli bir şekilde depolayın.</p>

<h3>
    <a name="step-1-install" href="#step-1-install"></a>
    Adım 1: Kurulum
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>composer require hpakdaman/multicarbon</code></pre>
</div>

<p>Bu, <strong>PHP 8.1+</strong> ve <strong>Carbon 2.x veya 3.x</strong> gerektirir. Laravel'de, hizmet sağlayıcı ve facade otomatik keşfetmeyle gelir — hiçbir şey kaydettirmeniz gerekmez.</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 Bir Jalali Tarihini Gösterin
</h3>

<p>Paket, bir durumda depolanan Gregoryen tarihini bir görüntüde Jalali'ye dönüştüren Blade direktifleri ile gelir:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>{{-- Herhangi bir depolanan tarih zamanını Jalali'ye dönüştür --}}

@jalali($post->published_at, ‘Y/m/d’) {{– 1404/06/15 –}}

{{– Güncel tarih, Hijri –}}
@hdate(‘Y/m/d’) {{– 1446/08/15 –}}

{{– Güncel Jalali tarihi, saat ile –}}
@jdate(‘Y/m/d H:i:s’)

<p>Kontrolcü değişikliği yok. Dönüştürme esnekliği yok. Direktif, geçerli Carbon uyumlu değeri alır ve hedef takvimde gösterir.</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 lambdasız yardımcılar:</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); // bir Unix zaman damgasından
hdate(<span class=”s1>’Y/m/d’); // “1446/08/15” — mevcut Hijri tarihi
multicarbon(); // kesit ekleyeceğiniz bir MultiCarbon örneği

<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 kural size acı çektirmez: <strong>tarihleri veritabanınıza 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 endişesi haline gelir.</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// Depolama - Laravel'in Gregoryen tarih zaman damgasını normal olarak depolamasını sağlayın</span>

$post->published_at = now();
$post->save();

// Gösterim – kenarda dönüştürün
echo MultiCarbon::fromCarbon($post->published_at)->jalali()->format(<span class=”s1>’Y/m/d’);

<p>Çünkü MultiCarbon, Carbon'u genişletir, <code>fromCarbon()</code> Laravel'in size zaten vermiş olduğu değeri kabul eder. Hiçbir migrasyona, şema değişikliğine ihtiyaç yoktur.</p>

<hr/>
<h2>
    <a name="what-you-actually-get" href="#what-you-actually-get"></a>
    Gerçekten Neler Elde Ediyorsunuz
</h2>

<p>Özellik yüzeyinin hızlı bir haritası, ne olduğunu anlayabilmeniz için:</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 örnekte</td>
            </tr>
            <tr>
                <td>Takvim duyarlı matematik</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, haftanın isimleri, AM/PM, <code>diffForHumans()</code></td>
            </tr>
            <tr>
                <td>Rakamsal gösterim</td>
                <td>Latin, Farsi (<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>Carbon'un kendisinden başka sıfır</td>
            </tr>
        </tbody>
    </table>
</div>

<p>Formlar ve içe aktarmalar için kullanışlı bir detay: takvim spesifik bir dizesini doğrudan çözümleyebilirsiniz, ilk olarak elle dönüştürmek zorunda kalmazsınız.</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// Kullanıcının yazdığı bir Jalali tarihini çözümleyin</span>

$mc = MultiCarbon::parseFormat(<span class=”s1>’Y/m/d’, <span class=”s1>’1404/01/15′);

// Bir Hijri tarihini çözümleyin
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>
    Tam Carbon Uyumluluğunu Nasıl Sürdürür?
</h2>

<p>MultiCarbon, property erişimi (<code>year</code>, <code>month</code>, <code>day</code>) ve bazı önemli metodları (<code>format()</code>, <code>setDate()</code>, <code>addMonths()</code>) yakalamak için <code>debug_backtrace()</code> kullanır. Bu yöntem, kullanan kodun kim olduğunu tespit eder.</p>

<p>İşte bu nedenle Carbon'un kendi iç işleyişi doğru çalışmaya devam ederken kullanıcı kodu, aktif takvimdeki yılı, ayı veya günü döndürür.</p>

<hr/>
<h2>
    <a name="when-to-reach-for-this" href="#when-to-reach-for-this"></a>
    Ne Zaman İhtiyaç Duyarsınız?
</h2>

<p>Açık bir açıklama için MultiCarbon nerelerde kullanılır:</p>
<ol>
    <li>
        <strong>Persce veya Arapça konuşan kullanıcılara hizmet veriyorsanız</strong> ve tarihleri kendi takvimlerinde göstermeniz gerekiyorsa. Bu, ana durumda geçerlidir.</li>
    <li>
        <strong>Zaten Carbon / Laravel kullanıyorsanız</strong> ve ikinci bir tarih türünün kodunuzu kirletmesini istemiyorsanız. MultiCarbon, tekrar yazmadan entegre olur.</li>
    <li>
        <strong>Takvim duyarlı matematik gereksiniminiz varsa</strong> — "3 Jalali ay ekle" ile "yaklaşık 90 gün ekle" aynı şey değildir ve MultiCarbon, ay uzunluğu farklılıklarını sizin için ele alır.</li>
</ol>

<p>Ne zaman kullanılmamalı: Uygulamanız sadece Gregoryen takvimdeysanız, bu durumda bu kütüphaneye ihtiyacınız yoktur — sıradan Carbon mükemmel bir seçenek olacaktır. MultiCarbon, yalnızca birden fazla takvim olduğunda yer kazanı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 Olarak Yayınladık)
</h2>

<p>MultiCarbon, <a href="https://unfoldcms.com/features" target="_blank" rel="noopener noreferrer">UnfoldCMS</a> üzerinde çalışırken ortaya çıktı; içerik farklı bölgelerde yayımlandığında farklı tarihler ile planlamaya ihtiyaç duydunuz. Jalali ve Hijri tarihlerinin her yerde Carbon tarihler gibi davranmasını istedik — yönetim panelinde, API'de, planlanan yayımda — iki tarih sistemi arasında kayıtsız kalmadık.</p>

<p>Bunu içsel olarak tutmak yerine, MIT lisansı altında yayımladık. Böylelikle aynı sorunu deneyimleyen herkes faydalanabilir. Eğer Laravel üzerinde bir <a href="https://unfoldcms.com/blog/laravel-cms-vs-wordpress-complete-comparison-2026/" target="_blank" rel="noopener noreferrer">CMS</a> geliştiriyorsanız veya <a href="https://unfoldcms.com/blog/unfoldcms-public-api-v1-launch" target="_blank" rel="noopener noreferrer">başsız REST API</a> ile çalışıyorsanız, aynı takvim kullandığınız alan doğrudan size sağlanmıştır.</p>

<p>Hemen kurabilirsiniz: <code>composer require hpakdaman/multicarbon</code>. Kaynak ve dökümantasyon <a href="https://github.com/hpakdaman/multicarbon" target="_blank" rel="noopener noreferrer">GitHub</a>'da bulunmaktadır.</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 mi alıyor?
</h3>

<p>Hayır — Carbon'u genişletmektir. Bir <code>MultiCarbon</code> örneği <em>bir</em> <code>Carbon</code> örneğidir, bu nedenle Carbon'u bekleyen tüm koda geçirebilirsiniz ve Carbon'un tüm metodları çalışır. Bunu yanında ekleyin, çıkarmazsınız.</p>

<h3>
    <a name="does-it-work-with-carbon-3" href="#does-it-work-with-carbon-3"></a>
    Carbon 3 ile çalışıyor mu?
</h3>

<p>Evet. MultiCarbon, PHP 8.1+ gerektirir ve hem Carbon 2.x hem de 3.x'i destekler. Projeniz için hangisini seçerseniz seviniriz.</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>
    Veritabanımda tarihler nasıl depolanacak?
</h3>

<p>Hayır. Tavsiye edilen desen, tarihleri Laravel'in yaptığı gibi Gregoryen (UTC) olarak depolamak ve yalnızca görüntülemede Jalali veya Hijri'ye dönüştürmektir. Bu yüzden herhangi bir migrasyona veya şemaya gerek yoktur.</p>

<h3>
    <a name="does-it-support-hijri-islamic-dates-or-only-jalali" href="#does-it-support-hijri-islamic-dates-or-only-jalali"></a>
    Hijri (İslami) tarihler destekleniyor mu, yoksa sadece Jalali mi?
</h3>

<p>Her ikisi de. MultiCarbon, Jalali (Güneş Hijri), Hijri (İslami Ay) ve Gregoryen'le çalışır. Her örnekte <code>->jalali()</code>, <code>->hijri()</code> ve <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 rakamları 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ı ile gösterir ve ay isimlerini, haftanın isimlerini ve "insanlar için fark" çıktısını yerelleştirir.</p>

<hr/>

<p><em>MultiCarbon, MIT lisansı altında açık kaynak olarak yayımlanmıştır. Geliştiriciler için tasarlanmış, kendinize ait bir CMS olarak UnfoldCMS içinde oluşturulmuştur. Kurulum için <code>composer require hpakdaman/multicarbon</code> — kaynak <a href="https://github.com/hpakdaman/multicarbon" target="_blank" rel="noopener noreferrer">GitHub</a>'da.</em></p>

<hr/>

<p>💬 <strong>Öncelikle 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 kendi kendine barındırılan bir CMS'dir. Eğer bu bilgiler yararlı olduysa — veya katılmıyorsanız — yorumlarda görüşmek üzere.</p>