// the find
overtrue/chinese-calendar
:date: 中国农历（阴历）与阳历（公历）转换与查询工具
A PHP library for converting between Gregorian and Chinese lunar calendar dates for any day from 1900 to 2100, returning the full stack of traditional metadata in one call — ganzhi, wuxing elements, zodiac animal, solar term, and constellation. Useful for PHP devs building zodiac/fortune-telling apps, lunar holiday calculators, or anything needing accurate CJK date math.
Zero runtime dependencies beyond ext-mbstring, using pure integer Julian day arithmetic — no floating-point rounding issues that plague naive calendar math. Lunar month and solar term data is verified day-by-day against the Hong Kong Observatory's official 1901-2100 tables and shipped as CSV test fixtures, so CI catches data regressions, not just logic bugs. The 2.x rewrite tightened error handling considerably: invalid input now throws TypeError/InvalidArgumentException instead of 1.x's silent wrong answers, and the whole codebase is strict_types with full parameter/return typing. Test setup also runs mutation testing (infection.json5) alongside phpstan and pint, which is more rigor than most small single-purpose calendar libraries bother with.
2.x requires PHP >= 8.5, which only became stable in late 2025 — that's going to keep most production codebases on the bugfix-only 1.x branch for quite a while. Documentation is Chinese-only with no English translation, which narrows the audience for a library that's genuinely useful to anyone needing lunar date math, not just Chinese-speaking devs. The 1900-2100 range is a hard wall — anything outside it just throws, so it's a non-starter for historical or long-range future calculations. The 2057 ganzhi edge case (new moon landing ~10 seconds before midnight Beijing time) is resolved by simply deferring to HKO's call rather than exposing the ambiguity, which is fine as a default but worth knowing if you're relying on exact correctness at that boundary.