README

PHP calendar functions

This package provides an implementation of the Arabic (Hijri), French Republican, Gregorian, Julian, Jewish and Persian (Jalali) calendars, plus a replacement for PHP‘s ext/calendar extension. It allows you to use the following PHP functions on servers that do not have the ext/calendar extension installed (such as HHVM).

• cal_days_in_month()
• cal_from_jd()
• cal_info()
• cal_to_jd()
• easter_date()
• easter_days()
• FrenchToJD()
• GregorianToJD()
• JDDayOfWeek()
• JDMonthName()
• JDToFrench()
• JDToGregorian()
• jdtojewish()
• JDToJulian()
• jdtounix()
• JewishToJD()
• JulianToJD()
• unixtojd()

How to use it

Add the package as a dependency in your composer.json file:

require {
    "fisharebest/ext-calendar": "~2.5"
}

Now you can use the PHP functions, whether ext/calendar is installed or not. Since version 2.2, it is no longer necessary to initialise these using Shim::create().

require 'vendor/autoload.php';
print_r(cal_info(CAL_GREGORIAN)); // Works in HHVM, or if ext-calendar is not installed

Alternatively, just use the calendar classes directly.

require 'vendor/autoload.php';

// Create calendars
$calendar = new Fisharebest\ExtCalendar\ArabicCalendar;
$calendar = new Fisharebest\ExtCalendar\FrenchCalendar;
$calendar = new Fisharebest\ExtCalendar\GregorianCalendar;
$calendar = new Fisharebest\ExtCalendar\JewishCalendar;
$calendar = new Fisharebest\ExtCalendar\JulianCalendar;
$calendar = new Fisharebest\ExtCalendar\PersianCalendar;

// Date conversions
$julian_day = $calendar->ymdToJd($year, $month, $day);
list($year, $month, $day) = $calendar->jdToYmd($julian_day);

// Information about days, weeks and months
$is_leap_year   = $calendar->isLeapYear($year);
$days_in_month  = $calendar->daysInMonth($year, $month);
$months_in_year = $calendar->monthsInYear();       // Not all calendars have 12
$months_in_year = $calendar->monthsInYear($year);  // In a specific year
$days_in_week   = $calendar->daysInWeek();         // Not all calendars have 7

// Which dates are valid for this calendar?
$jd = $calendar->jdStart();
$jd = $calendar->jdEnd();

// Miscellaneous utilities
$jewish = new JewishCalendar;
$jewish->numberToHebrewNumerals(5781, false); // "תשפ״א"
$jewish->numberToHebrewNumerals(5781, true);  // "ה׳תשפ״א"

Known restrictions and limitations

When faced with invalid inputs, the shim functions trigger E_USER_WARNING instead of E_WARNING. The text of the error messages is the same.

The functions easterdate() and jdtounixtime() use PHP‘s timezone, instead of the operating system‘s timezone. These may be different.

Compatibility with different versions of PHP

The following PHP bugs are emulated, according to the version of PHP being used. Thus the package always provides the same behaviour as the native ext/calendar extension.

• #54254 Jewish month "Adar" - fixed in PHP 5.5.

• #67960 Constants CAL_DOW_SHORT and CAL_DOW_LONG - found and fixed by this project - fixed in PHP 5.5.21 and 5.6.5.

• #67976 Wrong value in cal_days_in_month() for French calendar - found by this project.

Development and contributions

Due to the known restrictions above, you may need to run unit tests using TZ=UTC phpunit.

Pull requests are welcome. Please ensure you include unit-tests where applicable.

History

These functions were originally written for the webtrees project. As part of a refactoring process, they were extracted to a standalone library, given version numbers, unit tests, etc.

Future plans

• Support alternate leap-year schemes for the French calendar (true equinox, Romme, 128-year cycle) as well as the 4-year cycle.
• Support other calendars, such as Ethiopian, Hindu, Chinese, etc.