fallahalireza/persian-date-laravel

A modern, immutable, and optimized Jalali (Persian/Shamsi) calendar library for PHP and Laravel

v1.0.0 2026-05-28 19:04 UTC

Requires

• php: ^8.1
• nesbot/carbon: ^3.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.24
• orchestra/testbench: ^9.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpunit/phpunit: ^12.0

MIT

• Alireza Fallah

• date
• calendar
• laravel
• persian
• Jalali
• carbon
• shamsi

README

یک پکیج مدرن، immutable و بهینه برای تقویم جلالی (شمسی / فارسی) در PHP و Laravel.

✨ ویژگی‌های کلیدی

ویژگی	توضیح
Immutable	هر عملیات یک شیء جدید ایجاد می‌کند
Type-safe	استفاده کامل از strict_types و PHP 8.1+
Optimized	الگوریتم سریع تبدیل تاریخ با عملکرد O(1)
Lightweight	فقط وابسته به nesbot/carbon
Laravel Ready	Auto-discovery، Facade، Helper و Validation
Carbon Integration	تبدیل مستقیم بین Carbon و Jalali
Persian Locale	پشتیبانی کامل از اعداد و متن فارسی
Testable	تمام متدها pure و قابل تست

🚀 نصب

composer require fallahalireza/persian-date-laravel

Laravel به صورت خودکار Service Provider و Facade را register می‌کند.

⚡ استفاده سریع

use Fallahalireza\PersianDate\Jalali;

// تاریخ فعلی
$now = Jalali::now();

$now = jalali(); // helper

// ساخت تاریخ
$date = Jalali::create(1405, 3, 7, 14, 30, 0);

// تبدیل از Carbon
$date = Jalali::fromCarbon(now());

// تبدیل به Carbon
$carbon = $date->toCarbon();

🔄 Parse تاریخ

// جلالی
$date = Jalali::parse('1405/03/07');

$date = Jalali::parse('1405-03-07 14:30:00');

// میلادی → جلالی
$date = Jalali::parse('2026-05-28');

// از timestamp
$date = Jalali::fromTimestamp(time());

🧾 قالب‌بندی تاریخ

$date = Jalali::create(1405, 3, 7, 14, 30, 0);

$date->toDateString();      // 1405/03/07
$date->toTimeString();      // 14:30:00
$date->toDateTimeString();  // 1405/03/07 14:30:00

$date->toIso8601String();

$date->toFullPersianDate();
// چهارشنبه ۷ خرداد ۱۴۰۵

$date->format('Y/m/d');

$date->formatEnglish('Y/m/d');

🌍 Locale

Jalali::setLocale('fa'); // پیش‌فرض

Jalali::setLocale('en');

➕ عملیات تاریخ (Immutable)

$date = Jalali::create(1405, 3, 7);

// افزودن
$date->addDays(10);
$date->addMonths(2);
$date->addYears(1);

$date->addWeeks(3);
$date->addHours(5);
$date->addMinutes(30);

// کاهش
$date->subDays(5);
$date->subMonths(1);
$date->subYears(2);

📌 Boundary Methods

$date->startOfDay();
$date->endOfDay();

$date->startOfWeek();
$date->endOfWeek();

$date->startOfMonth();
$date->endOfMonth();

$date->startOfYear();
$date->endOfYear();

$date->startOfQuarter();
$date->endOfQuarter();

⚖️ مقایسه تاریخ‌ها

$a = Jalali::create(1405, 1, 1);
$b = Jalali::create(1405, 3, 7);

$a->lt($b); // true
$a->gt($b); // false
$a->eq($a); // true

$b->between($a, $b);

$date->isToday();
$date->isFuture();
$date->isPast();

$date->isWeekend();

$date->isLeapYear();

📏 اختلاف تاریخ‌ها

$a = Jalali::create(1405, 1, 1);
$b = Jalali::create(1405, 3, 7);

$a->diffInDays($b);

$a->diffInMonths($b);

$a->diffInYears($b);

$a->diffInHours($b);

$a->diffInSeconds($b);

🔍 Getter ها

$date = Jalali::create(1405, 3, 7, 14, 30, 45);

$date->year;
$date->month;
$date->day;

$date->hour;
$date->minute;
$date->second;

$date->dayOfWeek;

$date->dayOfYear;

$date->weekOfYear;

$date->quarter;

$date->timestamp;

$date->timezone;

$date->daysInMonth();

🧠 Human Diff

$date->diffForHumans();

// ۲ روز پیش
// ۳ ماه بعد

🧩 Carbon Integration

$jalali = now()->toJalali();

$carbon = $jalali->toCarbon();

✅ Validation Rules (Laravel)

'birth_date' => ['required', 'jdate'],

'start_date' => [
    'required',
    'jdate',
    'jdate_after:1400/01/01',
],

'end_date' => [
    'required',
    'jdate_before:1410/01/01',
],

'event_date' => [
    'required',
    'jdate_after_or_equal:' . jalali()->toDateString(),
],

🛠 Helper Function

jalali();

jalali(now());

jalali('1405/03/07');

🧪 تست

composer test

🎨 فرمت کد

composer format

🔍 آنالیز استاتیک

composer analyse

📄 مجوز

MIT License © 2026 Alireza Fallah