PHPackages                             eram/daynum - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. eram/daynum

ActiveLibrary[Utility & Helpers](/categories/utility)

eram/daynum
===========

Immutable, zero-runtime-dependency multi-calendar library for PHP 8.1+. Gregorian, Jalali (Shamsi), and Hijri, differentially tested against ICU.

v1.0.0-beta.1(1mo ago)06↓100%MITPHPPHP >=8.1CI failing

Since Apr 12Pushed 1mo agoCompare

[ Source](https://github.com/eramhq/daynum)[ Packagist](https://packagist.org/packages/eram/daynum)[ Docs](https://github.com/eramhq/daynum)[ RSS](/packages/eram-daynum/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (2)Versions (2)Used By (0)

Daynum
======

[](#daynum)

**Immutable, zero-runtime-dependency, multi-calendar PHP library.**

Daynum is a clean, single-package replacement for the 3–4 libraries PHP developers currently glue together to get Gregorian + Jalali (Shamsi) + Hijri support. It targets PHP 8.1+, requires no `ext-intl` at runtime, pulls no transitive dependencies, and is differentially tested against ICU on ~220,000 dates per calendar per CI build.

v1 ships **Gregorian**, **Jalali**, and **Hijri** (Saudi Umm al-Qura + tabular civil), with **English**, **Persian**, and **Arabic** locales.

What Daynum is (and isn't)
--------------------------

[](#what-daynum-is-and-isnt)

**Daynum IS:** multi-calendar date conversion + formatting, immutable arithmetic, locale-aware formatting with PHP `date()` tokens, a zero-dependency ICU-tested replacement for `morilog/jalali`.

**Daynum is NOT:** a timezone library (use `toDateTimeImmutable()` for DST math), a relative-date parser ("next Monday"), a Carbon replacement (Carbon covers Gregorian + timezones; Daynum covers multi-calendar + correctness), or a framework bridge.

> **Naming caveat: `Instant` is civil, not UTC.** Unlike `java.time.Instant`, Daynum's `Instant` is a calendar-neutral civil datetime: `(JDN, time-of-day, timezone label)`. Two instants with the same JDN and time but different tzLabels represent different physical moments. See [docs/en/concepts.md](docs/en/concepts.md#instant-is-civil-not-utc).

FeatureDaynumCarbonmorilog/jalaliext-intlJalaliBirashk 33-yearNoBirashk (same)BorkowskiHijri UAQBundled tableNoNoRuntime ICUHijri CivilYesNoNoYesRuntime depsZerosymfony/\*nesbot/carbonext-intlImmutableYesOptionalNoN/ATestingICU differentialUnit testsUnit testsIS the oracleInstall
-------

[](#install)

```
composer require eram/daynum:^1.0@beta
```

Quick start
-----------

[](#quick-start)

```
use Eram\Daynum\Instant;
use Eram\Daynum\Calendar\Jalali\JalaliView;

// Construction — one calendar to pick from, three calendars to read back
$d = Instant::fromGregorian(2026, 4, 8, 14, 30, 0, 'Asia/Tehran');

$d->gregorian()->format('Y-m-d');                   // "2026-04-08"
$d->jalali()->format('Y/m/d');                      // "1405/01/19"
$d->hijri()->format('j F Y');                       // "21 Shawwal 1447"

// Persian locale + Persian digits
$d->jalali()->withLocale('fa')->withDigits('persian')->format('l j F Y');
// "چهارشنبه ۱۹ فروردین ۱۴۰۵"

// Immutable arithmetic — returns Instant, re-enter a view to format
$next = $d->jalali()->addMonths(1);                 // Instant
$next->jalali()->format('Y/m/d');                   // "1405/02/19"

// Strict parsing — digits in any script are normalized
JalaliView::parseExact('۱۴۰۵/۰۱/۱۹', 'Y/m/d');     // Instant
JalaliView::tryParseExact('nope', 'Y/m/d');         // null

// JSON round-trip contract
json_encode($d);
// {"jdn":2461139,"secondsOfDay":52200,"tzLabel":"Asia/Tehran"}
Instant::fromArray(json_decode(json_encode($d), true))->equals($d);   // true

// Escape hatch to native PHP for real timezone math
$d->toDateTimeImmutable();
```

Documentation
-------------

[](#documentation)

**Learn**

- [Getting Started](docs/en/getting-started.md) — install, first example, 5-minute tour
- [Concepts](docs/en/concepts.md) — civil vs. UTC, `Instant` vs. view, JDN, immutability
- [Cookbook](docs/en/cookbook.md) — 10+ task-indexed recipes
- [FAQ](docs/en/faq.md) — surprising-but-intentional design decisions

**Calendars**

- [Gregorian](docs/en/calendars/gregorian.md) · [Jalali](docs/en/calendars/jalali.md) · [Hijri (Umm al-Qura)](docs/en/calendars/hijri-umm-al-qura.md) · [Hijri (civil)](docs/en/calendars/hijri-civil.md)

**Reference**

- [API Reference](docs/en/api-reference.md) — every type and method
- [Formatting](docs/en/formatting.md) · [Parsing](docs/en/parsing.md) · [Arithmetic](docs/en/arithmetic.md)
- [Localization](docs/en/localization.md) · [Timezones](docs/en/timezones.md) · [Exceptions](docs/en/exceptions.md) · [Serialization](docs/en/serialization.md)

**Migration & attribution**

- [Migrating from morilog/jalali](docs/en/migration-from-morilog-jalali.md)
- [Algorithms and attribution](docs/en/algorithms-and-attribution.md)

Contributing
------------

[](#contributing)

Bug reports, docs fixes, new locales, and new calendar systems are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for testing, fixture regeneration, and the "how to add a new calendar" checklist.

Links
-----

[](#links)

- [CHANGELOG.md](CHANGELOG.md) — release notes
- [LICENSE](LICENSE) — MIT
- [Issue tracker](https://github.com/eramhq/daynum/issues)

License
-------

[](#license)

MIT. See [LICENSE](LICENSE).

###  Health Score

33

—

LowBetter than 73% of packages

Maintenance88

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity28

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/903ed9822434a3fc804c42a8013c98a91fc6766b514b077268bea70cb957e41f?d=identicon)[navidk](/maintainers/navidk)

---

Top Contributors

[![navidkashani](https://avatars.githubusercontent.com/u/1286738?v=4)](https://github.com/navidkashani "navidkashani (29 commits)")

---

Tags

gregorianhijrijalalimulti-calendar-aggregationdatecalendarimmutableJalaliarabicpersianshamsihijrigregoriansolar hijriummalquraislamic-calendar

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/eram-daynum/health.svg)

```
[![Health](https://phpackages.com/badges/eram-daynum/health.svg)](https://phpackages.com/packages/eram-daynum)
```

###  Alternatives

[fisharebest/ext-calendar

Implementation of the Arabic (Hijri), French, Gregorian, Jewish, Julian and Persian (Jalali) calendars. Also provides a replacement for the PHP ext/calendar extension.

36497.9k10](/packages/fisharebest-ext-calendar)[aeon-php/calendar

PHP type safe, immutable calendar library

20410.2M16](/packages/aeon-php-calendar)[hekmatinasser/verta

This Package helps developers to work with Jalali Datetime class for Laravel Framework PHP

661541.4k28](/packages/hekmatinasser-verta)[p3ym4n/jdate

Date converter from Jalali to Georgian and vice versa. It has Carbon instance inside and it's Laravel friendly.

101.8k2](/packages/p3ym4n-jdate)[mohamedsabil83/laravel-hijrian

Hijri-Gregorian date converter for Laravel

1322.0k](/packages/mohamedsabil83-laravel-hijrian)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)