Jalali Dates in Modern PHP: Building ParsiDate — Immutable, Zero-Dependency, with Holidays Built In

Description and use

ParsiDate is a PHP library for Jalali dates that offers immutability, zero dependencies, built‑in holiday data, Persian digit support, and Hijri conversion.

Problem

Developers building software for Persian speakers need reliable Jalali (Solar Hijri) dates in PHP, but existing libraries are outdated, mutable, or require maintenance of holiday lists.

Outcome

ParsiDate offers immutable date objects, zero dependencies, built‑in holiday data, Persian digit support, and Hijri conversion, simplifying Jalali date handling in PHP projects.

Workflow

• Install via Composer: composer require mahdyaralipor/parsidate
• Create a date: $date = ParsiDate::create(1403,1,1);
• Add days immutably: $later = $date->addDays(10);
• Check holidays: $date->isHoliday(); $date->holidayName();
• Add workdays skipping Fridays and holidays: $date->addWorkdays(5);
• Iterate periods: $period = ParsiPeriod::ofMonth(1403,1); foreach($period->fridays() as $friday){ echo $friday->format('Y/m/d'); }
• Parse Persian digits: ParsiDate::parse('۱۴۰۳/۰۶/۱۵');
• Convert to Hijri: $date->toHijri();

Evidence

If you build software for 85+ million Persian speakers, you need Jalali (Solar Hijri) dates.

Source

I built ParsiDate to fix that for my own projects. It's now at v1.1.0, MIT licensed, with 136 passing tests:

Source

1. Immutable by default. Every arithmetic method returns a new instance:

Source

1. Zero dependencies. composer.json requires exactly one thing: php: ^8.1. No Carbon, no framework, no polyfills.

Source

1. Holidays are data, not your problem. Official Iranian public holidays (1400–1406, verified date-by-date against the official calendar) ship inside the package, with an API for variable holidays:

Source

1. Persian digits everywhere. Parsing and formatting both understand ۰۱۲۳۴۵۶۷۸۹, because real user input uses them:

Source