Limits

These limits are on purpose. They keep every call cheap and predictable, and they stop untrusted input from turning into a wrapped-around date or an expensive computation. Going over a limit always raises a documented RtlyKitException (see Error handling) or, for validators, gives an invalid Result.

Calendar year ranges

Every supported date of every calendar maps to a Gregorian year between 1 and 9999. So any value the classes produce fits in a DateTimeImmutable without wrapping around. The ranges are the public constants MIN_YEAR and MAX_YEAR:

<?php
require __DIR__.'/vendor/autoload.php';

use RtlyKit\Calendar\{Hebrew, Hijri, Jalali};

foreach ([Jalali::class, Hijri::class, Hebrew::class] as $class) {
    printf(
        "%-7s %5d..%-5d  %s .. %s\n",
        (new ReflectionClass($class))->getShortName(),
        $class::MIN_YEAR,
        $class::MAX_YEAR,
        $class::create($class::MIN_YEAR, 1, 1)->toGregorian()->format('Y-m-d'),
        $class::create($class::MAX_YEAR, 1, 1)->toGregorian()->format('Y-m-d'),
    );
}
// Jalali   -620..9377   0001-03-21 .. 9998-03-20
// Hijri       1..9665   0622-07-19 .. 9998-10-12
// Hebrew   3762..13759  0001-09-06 .. 9998-10-15

Every entry point follows the range: make, create, createFromFormat, Unix timestamps, add*() and sub*() (including huge amounts), the helpers and the Carbon macros. A value outside the range throws InvalidDateException. Nothing returns a wrapped-around date, and no TypeError or ValueError escapes.

Amounts and timestamps

• An addDays() or subDays() amount (and hours, minutes, seconds) larger than the span of the whole supported calendar (about 3.7 million days, or the same span in hours, minutes or seconds) is refused up front with InvalidDateException . A smaller amount that lands outside the supported years is refused too.
• A Unix timestamp must fall within Gregorian years 1 to 9999 (with a little room for the time zone). Anything further out is refused.
• Hebrew::addMonths() and addYears() take the same short time however large the amount is.

String-year thresholds

A string such as 1405/01/01 or 1405-01-01 passed to make() or a helper is read as a date of the calendar itself when the year is below the threshold. Otherwise it is read as a Gregorian string:

The text must have exactly the shape Y/m/d or Y-m-d, with an optional time ( H:i , H:i:s or H:i:s.u after a space, T or t ) and an optional zone designator ( Z , +03:30 , +0330 or +03 , within ±14:00) that sets the time zone. Text that starts like a date of the calendar but has more (a zone name such as UTC , PM ) or less, a bare run of 3 to 8 digits, and a 5-digit year in Jalali or Hijri all throw InvalidDateException . Hebrew accepts years of 4 or 5 digits (up to 13759). A no-break space, ZWNJ, LRM and RLM count as spaces.

To pass a real Gregorian date below the threshold (for example the year 999), use a DateTimeImmutable. It is never reinterpreted. See the FAQ.

Umm al-Qura range

• The embedded Umm al-Qura month table covers AH 1300 to 1500 (1882-11-12 to 2077-11-16). Outside it, and always for HijriVariant::Tabular , Hijri uses arithmetic rules that can differ from observation by a day or two. Hijri::hasUmmAlQuraData($year) tells you whether a year is covered. Years AH 1318 to 1500 are the ones checked against the official KACST calendar ( Hijri::ummAlQuraVerifiedRange() ).
• IranHolidays uses official or reported dates for the Jalali years 1380 to 1405. For other years it reports Islamic holidays only inside the Umm al-Qura range. Outside it, and for years before the Hijri epoch, only the fixed Jalali holidays are returned, without an exception. all() , allTitles() and allFixed() work for every Jalali year from -620 to 9377.

Input size caps

The caps are part of the contract (see API stability).

Number ranges

use function RtlyKit\number_to_words;

echo number_to_words(999999999, 'ar'), "\n";
// تسعمئة وتسعة وتسعون مليون وتسعمئة وتسعة وتسعون ألف وتسعمئة وتسعة وتسعون
// number_to_words(str_repeat('9', 28), 'ar') throws InvalidNumberException (number_too_large, limit "10^27 - 1")
// number_to_words(str_repeat('9', 22)) throws InvalidNumberException (number_too_large, limit "10^21 - 1")

Setting ranges

Data coverage

See Accuracy and data for what these tables are based on.

Platform limits

PHP 8.2 to 8.5 with no extension beyond a standard build, Laravel 11, 12 and 13, and Carbon 3. See API stability.