README

Persian (Jalali/Shamsi) calendar extension for Carbon - Full Laravel 9/10/11/12 support with seamless date formatting, conversion, and human-readable diffs in Farsi.

Features

🗓️ Gregorian ↔ Jalali conversion - Accurate bidirectional date conversion
📝 Persian date formatting - Full support for PHP date format characters
🔢 Persian numerals - Native Persian numeral output (۱۴۰۳/۰۷/۱۵)
📅 Month & day names - Full Persian names (فروردین، شنبه)
⏰ Human-readable diffs - Persian relative time (۲ روز پیش)
🔄 Drop-in Carbon replacement - All Carbon methods work seamlessly
🚀 Laravel 9/10/11/12 compatible - Auto-discovery service provider
✅ Carbon 2.x & 3.x support - Works with both Carbon 2 and Carbon 3

Requirements

PHP 8.1+
Carbon 2.67+ or 3.0+
Laravel 9/10/11/12 (optional, for service provider features)

Installation

Install via Composer:

composer require hpakdaman/jcarbon

Laravel will automatically discover the service provider. For other frameworks, the helpers are available immediately after installation.

Quick Start

use Hpakdaman\Jcarbon\Jcarbon;

// Create from now
$date = Jcarbon::now();
echo $date->jformat('Y/m/d');  // ۱۴۰۳/۱۱/۲۵

// Create from Jalali date
$date = Jcarbon::createJalali(1403, 7, 15);
echo $date->format('Y-m-d');   // 2024-10-06 (Gregorian)

// Access Jalali properties
echo $date->jYear;      // 1403
echo $date->jMonth;     // 7
echo $date->jDay;       // 15
echo $date->jMonthName; // مهر
echo $date->jDayName;   // شنبه

Usage

Creating Instances

use Hpakdaman\Jcarbon\Jcarbon;

// From current time
$now = Jcarbon::now();
$today = Jcarbon::today();

// From Jalali date components
$date = Jcarbon::createJalali(1403, 7, 15);           // Date only
$date = Jcarbon::createJalali(1403, 7, 15, 14, 30);   // With time

// From Jalali string
$date = Jcarbon::createFromJalaliFormat('Y/m/d', '1403/07/15');
$date = Jcarbon::createFromJalaliFormat('Y/m/d H:i', '1403/07/15 14:30');

// With Persian numerals
$date = Jcarbon::createFromJalaliFormat('Y/m/d', '۱۴۰۳/۰۷/۱۵');

// From Carbon instance
$carbon = Carbon::now();
$jcarbon = Jcarbon::instance($carbon);

// Tehran timezone shortcut
$tehran = Jcarbon::todayTehran();

Formatting

$date = Jcarbon::createJalali(1403, 7, 15, 14, 30);

// With Persian numerals (default)
echo $date->jformat('Y/m/d');           // ۱۴۰۳/۰۷/۱۵
echo $date->jformat('j F Y');           // ۱۵ مهر ۱۴۰۳
echo $date->jformat('l j F Y');         // شنبه ۱۵ مهر ۱۴۰۳
echo $date->jformat('Y/m/d H:i:s');     // ۱۴۰۳/۰۷/۱۵ ۱۴:۳۰:۰۰

// With English numerals
echo $date->jformat('Y/m/d', false);    // 1403/07/15

// Common format shortcuts
echo $date->toJalaliDateString();       // ۱۴۰۳/۰۷/۱۵
echo $date->toJalaliDateTimeString();   // ۱۴۰۳/۰۷/۱۵ ۱۴:۳۰:۰۰
echo $date->toJalaliHumanDate();        // ۱۵ مهر ۱۴۰۳
echo $date->toJalaliFullDate();         // شنبه ۱۵ مهر ۱۴۰۳

Format Characters

Char	Description	Example
Y	Full year	۱۴۰۳
y	2-digit year	۰۳
m	Month (zero-padded)	۰۷
n	Month	۷
F	Full month name	مهر
M	Short month name	مهر
d	Day (zero-padded)	۱۵
j	Day	۱۵
l	Full day name	شنبه
D	Short day name	ش
w	Day of week (0=Sat)	۰
t	Days in month	۳۰
L	Leap year (0/1)	۱
H	Hour (24-hour)	۱۴
i	Minutes	۳۰
s	Seconds	۰۰
A/a	AM/PM	ب.ظ

Properties

$date = Jcarbon::createJalali(1403, 7, 15);

// Jalali properties
$date->jYear;        // 1403
$date->jMonth;       // 7
$date->jDay;         // 15
$date->jMonthName;   // مهر
$date->jMonthShort;  // مهر
$date->jDayName;     // شنبه
$date->jDayShort;    // ش
$date->jDayOfWeek;   // 0 (Saturday=0, Friday=6)

// Gregorian properties (inherited from Carbon)
$date->year;         // 2024
$date->month;        // 10
$date->day;          // 6

Human-Readable Diffs (Persian)

$date = Jcarbon::now()->subDays(2);
echo $date->diffForHumansJalali();        // ۲ روز پیش

$date = Jcarbon::now()->addMonths(3);
echo $date->diffForHumansJalali();        // ۳ ماه دیگر

$date = Jcarbon::now()->subSeconds(5);
echo $date->diffForHumansJalaliSmart();   // همین الان

// Absolute (no ago/from now)
echo $date->diffForHumansJalali(null, true);  // ۲ روز

Date Manipulation

All Carbon methods work and update the Jalali cache automatically:

$date = Jcarbon::createJalali(1403, 7, 15);

$date->addDay();
echo $date->jDay;    // 16

$date->addMonth();
echo $date->jMonth;  // 8

$date->addYear();
echo $date->jYear;   // 1404

$date->subWeek();
$date->addHours(5);
// ... all Carbon methods work

Helper Functions

// Create Jcarbon instance
$date = jcarbon();
$date = jcarbon('2024-10-06');
$date = jcarbon($carbonInstance);

// Format date
echo jdate();                              // Current date: ۱۴۰۳/۱۱/۲۵
echo jdate($date);                         // ۱۴۰۳/۰۷/۱۵
echo jdate($date, 'j F Y');                // ۱۵ مهر ۱۴۰۳
echo jdate($date, 'Y/m/d', false);         // 1403/07/15

// Get current time
$now = jnow();
$today = jtoday();

// Conversion helpers
gregorian_to_jalali(2024, 10, 6);  // [1403, 7, 15]
jalali_to_gregorian(1403, 7, 15);  // [2024, 10, 6]

// Numeral conversion
to_persian_numerals(1403);    // ۱۴۰۳
to_english_numerals('۱۴۰۳');  // 1403

// Utility
is_jalali_leap_year(1403);       // true
jalali_days_in_month(1403, 12);  // 30

Blade Directives (Laravel)

{{-- Format a date --}}
@jdate($post->created_at)
@jdate($post->created_at, 'j F Y')

{{-- Current date --}}
@jnow
@jnow('l j F Y')

{{-- Convert numbers to Persian --}}
@persianNum($count)
@persianNum(1234)  {{-- ۱۲۳۴ --}}

Array Output

$date = Jcarbon::createJalali(1403, 7, 15, 14, 30);

$array = $date->toJalaliArray();
// [
//     'gregorian' => [
//         'year' => 2024,
//         'month' => 10,
//         'day' => 6,
//         'formatted' => '2024-10-06',
//     ],
//     'jalali' => [
//         'year' => 1403,
//         'month' => 7,
//         'day' => 15,
//         'month_name' => 'مهر',
//         'day_name' => 'شنبه',
//         'formatted' => '1403/07/15',
//         'formatted_persian' => '۱۴۰۳/۰۷/۱۵',
//     ],
//     'time' => [
//         'hour' => 14,
//         'minute' => 30,
//         'second' => 0,
//     ],
//     'timestamp' => 1728216600,
//     'timezone' => 'UTC',
// ]

Jalali Calendar Reference

Months

#	Name	Days
1	فروردین (Farvardin)	31
2	اردیبهشت (Ordibehesht)	31
3	خرداد (Khordad)	31
4	تیر (Tir)	31
5	مرداد (Mordad)	31
6	شهریور (Shahrivar)	31
7	مهر (Mehr)	30
8	آبان (Aban)	30
9	آذر (Azar)	30
10	دی (Dey)	30
11	بهمن (Bahman)	30
12	اسفند (Esfand)	29 (30 in leap years)

Days of Week

#	Name	Short
0	شنبه (Saturday)	ش
1	یک‌شنبه (Sunday)	ی
2	دوشنبه (Monday)	د
3	سه‌شنبه (Tuesday)	س
4	چهارشنبه (Wednesday)	چ
5	پنج‌شنبه (Thursday)	پ
6	جمعه (Friday)	ج

Known Leap Years

1399, 1403, 1408, 1412, 1416, 1420, 1424...

Testing

composer test

hpakdaman / jcarbon

Maintainers

Details