README

A precision-grade polyfill for PHP's ext/calendar. Built from php-src sources and tuned for behavioral parity across PHP 8.1 - 8.5.

This is a maintained fork of roukmoute/polyfill-calendar that focuses on complete feature coverage, strict compatibility, and predictable runtime behavior. The public namespace remains Roukmoute\Polyfill\Calendar to preserve drop-in compatibility.

Why this exists

Full ext/calendar function surface for PHP 8.1 - 8.5.
php-src aligned logic, including validation, overflow guards, and edge cases.
Drop-in: functions are defined only when the extension is missing.
Deterministic timezone resolution that mirrors the extension.
Strict types and comprehensive tests.

Installation

composer require softcreatr/polyfill-calendar

Usage

Global functions (drop-in)

The Composer autoloader registers the polyfill functions when ext/calendar is not available.

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

$info = cal_info(CAL_GREGORIAN);
$jd = gregoriantojd(4, 22, 2000);
$easter = easter_date(2000);
$hebrew = jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM);

Class API

You can call the internal conversion classes directly when you want explicit control over the implementation.

<?php
use Roukmoute\Polyfill\Calendar\Calendar;
use Roukmoute\Polyfill\Calendar\Easter;
use Roukmoute\Polyfill\Calendar\Gregor;
use Roukmoute\Polyfill\Calendar\Julian;

$info = Calendar::cal_info(Calendar::CAL_GREGORIAN);
$jd = Gregor::toSDN(2000, 4, 22);
$gregorian = Julian::jdtogregorian($jd);
$daysAfterMarch21 = Easter::easter_days(2000);

Deterministic timezone behavior

easter_date() and unixtojd() resolve the system timezone the same way as ext/calendar (TZ environment, /etc/timezone, /etc/localtime, PHP default). If you need deterministic results in tests, set TZ explicitly:

putenv('TZ=UTC');
date_default_timezone_set('UTC');

Supported functions

Compatibility

PHP 8.1 - 8.5 only. PHP 7 support is intentionally dropped.
If ext/calendar is installed, native functions are used instead.

Testing

The test suite is designed for parity with php-src and targets full code coverage with Xdebug.

XDEBUG_MODE=coverage php vendor/bin/phpunit --coverage-text --show-uncovered-for-coverage-text

Credits

Based on roukmoute/polyfill-calendar and the ext/calendar sources in php-src.

License

This library is released under the MIT license.

softcreatr / polyfill-calendar

Maintainers

Details