Skip to content

Latest commit

 

History

History
140 lines (107 loc) · 5.74 KB

README.md

File metadata and controls

140 lines (107 loc) · 5.74 KB
Raw

Build Status Coverage Status SensioLabsInsight Scrutinizer Code Quality Code Climate

PHP calendar functions

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

How to use it

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

require {
    "fisharebest/ext-calendar": "2.*"
}

If you want to create the “shim” functions, you must tell the package to create them.

// Put this in your bootstrap.php or similar.
\Fisharebest\ExtCalendar\Shim::create();

Now you can use the PHP functions, whether ext/calendar is installed or not:

print_r(cal_info(CAL_GREGORIAN)); // Works in HHVM!

Alternatively, just use the calendar classes directly.

use Fisharebest\ExtCalendar;

// Create a calendar
$calendar = new ArabicCalendar;
$calendar = new FrenchCalendar;
$calendar = new GregorianCalendar;
$calendar = new JewishCalendar;
$calendar = new JulianCalendar;
$calendar = new PersianCalendar;

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

// Days, weeks and months
$is_leap_year  = $calendar->isLeapYear($year);
$month_length  = $calendar->daysInMonth($year, $month);
$number_months = $calendar->monthsInYear();  // Including leap-months
$week_length   = $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/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, and follow the existing coding conventions. These are to follow PSR standards, except for:

  • tabs are used for indentation
  • opening braces always go on the end of the previous line

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.