如何使用Composer引入 PHP-Lunar 库实现阳历与阴历的相互转换算法

先说结论：PHP-Lunar 并不是一个能直接通过 Composer 安装的公开包。它既没有在 Packagist 上注册，也没有官方维护团队，所以当你尝试执行 composer require php-lunar/php-lunar 时，终端回馈给你的只会是 Package not found 的报错信息。

为什么 Composer 找不到 php-lunar/php-lunar

网上流传的那些所谓“PHP-Lunar”教程或代码，基本可归为三类：一是某个开发者从私有仓库或 fork 项目中改写的农历转换逻辑，没有统一的命名规范，自然也没注册到 Packagist；二是把 Python 的 lunardate 或 Ja va 的 ChineseCalendar 张冠李戴，误当作 PHP 实现来宣传；三是部分中文博客把自己写的函数或者旧版 calendars 类库硬贴上了这个标签。

实际上，一个稳定、可维护、能通过 Composer 一键安装的农历转换方案，确实存在，只是名字不叫 PHP-Lunar。

可用的替代方案：overtrue/lara vel-chinese-calendar（Lara vel 场景）

这是目前最接近需求、也最省心的选择。它底层基于权威农历算法，节气、闰月校验都做得相当规范，不仅适用于 Lara vel 项目，纯 PHP 环境下也能直接调用。

执行安装命令很简单，一行代码搞定：

composer require overtrue/lara vel-chinese-calendar

基础用法示例：

$calendar = new OvertrueChineseCalendarCalendar();
// 阳历转阴历
$lunar = $calendar->solarToLunar(2024, 10, 1); // 返回 ['year'=>2024, 'month'=>8, 'day'=>28, 'leap'=>false, ...]
// 阴历转阳历
$solar = $calendar->lunarToSolar(2024, 8, 28, false); // 返回 ['year'=>2024, 'month'=>10, 'day'=>1]

有几个地方需要特别留意：

• 该库默认只支持 1900–2100 年区间，超出这个范围会返回 null
• 阴历日期中的 leap 参数必须明确传 true 或 false，不然闰月判断很容易出错
• 精度只到日粒度，不支持时辰或更细的时间戳转换

纯 PHP 项目用 gaozhi/lunar（轻量无框架依赖）

如果你不需要 Lara vel 那一套，只想轻装上阵，gaozhi/lunar 是个不错的选择。它没有任何外部依赖，已经发布在 Packagist，兼容 PHP 7.4 以上版本。

composer require gaozhi/lunar

调用方式极其简洁：

use GaozhiLunarLunar;
$lunar = new Lunar();
echo $lunar->dateToLunar('2024-10-01'); // "二〇二四年八月廿八"
echo $lunar->lunarToDate('二〇二四年八月廿八'); // "2024-10-01"

当然，它也有自己的限制：

• 输入格式非常严格：dateToLunar() 要求 Y-m-d 格式，lunarToDate() 则必须带中文数字和“年/月/日”结构
• 返回结果是格式化字符串，不是结构化数组，想要提取年月日需要自己用 preg_match 处理
• 节气信息没有暴露成独立接口，如果需要立春、冬至之类的数据，得另外查表或扩展

自己封装时最容易忽略的三个细节

假如你决定自己动手封装农历转换算法，那下面这三个坑几乎是必踩的：

• 农历“正月初一”并不是一个固定的阳历日期——它由天文朔日（新月时刻）决定，需要查阅《紫金历》或中科院紫金山天文台的数据，千万别简单用“1月21日到2月20日之间”去估算
• 闰月处理必须同时判断当年闰几月以及具体哪个月是闰月，漏掉任何一个条件，后续所有月份都会偏移
• PHP 的 strtotime() 和 DateTime 默认只认识公历，传入“二〇二四年八月廿八”这种字符串会直接报错，必须先做字符串规整，再进入算法运算

真正可靠的农历转换，核心从来不在代码行数多少，而在于所用天文常数和闰周规则是否与最新《农历编算规范》保持一致。别轻信“几百行搞定阴阳历”这种说法——光是 1900–2100 年间闰月分布表，就得嵌入 40 多条硬编码规则。