README

HijriDate

Laravel Hijri日期辅助包。支持直接显示阿拉伯语、孟加拉语、迪维希语和英语日期，同时支持进一步自定义或添加您选择的语言。

安装
创建日期
- 自定义Hijri和公历日期之间的转换方式
可用方法
- 转换
- 计算
- 比较
- 格式化
类型转换
验证
本地化
- 添加语言
从v1迁移到v2

安装

composer require remls/hijri-date

发布配置文件

php artisan vendor:publish --provider="Remls\HijriDate\HijriDateServiceProvider" --tag="config"

创建日期

以下所有方法都返回一个 Remls\HijriDate\HijriDate 实例。

use Carbon\Carbon;

new HijriDate();                    // 1st Muharram 1000
new HijriDate(1443, 9, 1);          // 1st Ramadan 1443
HijriDate::parse('1443-09-01');     // 1st Ramadan 1443

// From Gregorian
HijriDate::createFromGregorian();              // Today's date
today_hijri();                                 // Today's date
HijriDate::createFromGregorian('1991-12-01');  // 20th Jumada al-Ula 1412
$input = Carbon::parse('2002-03-04');
HijriDate::createFromGregorian($input);        // 12th Dhul-Hijja 1422

自定义Hijri和公历日期之间的转换方式

默认情况下，该包使用马尔代夫公历与回历日期之间的外部映射来在两者之间进行转换。此映射被缓存并用于后续转换。

您可以通过更改 config/hijri.php > conversion.cache_period 来自定义映射的缓存时间。

您可以通过运行 php artisan hijri:fetch 来手动从外部源重新获取数据。

该包还提供了一个使用计算而不是映射来转换日期的替代类。您可以通过更改 config/hijri.php > conversion.converter 到 \Remls\HijriDate\Converters\MaldivesEstimateG2HConverter::class 来启用它。

您可以通过以下方式自定义日期转换：

在 config/hijri.php > conversion.data_url 中提供您自己的映射
在 config/hijri.php > conversion.converter 中提供您自己的自定义转换类
- 该类必须实现 \Remls\HijriDate\Converters\Contracts\GregorianToHijriConverter。

可用方法

转换

// Gregorian to Hijri
HijriDate::createFromGregorian('1991-12-01'); // returns HijriDate

// Hijri to Gregorian
$date = new HijriDate(1443, 9, 1);
$date->getGregorianDate();                    // returns Carbon

您可以详细地自定义转换方式，请参阅此处。

计算

$date = new HijriDate(1443, 9, 1);   // 1st Ramadan 1443
$date->addDays(1);                   // 2nd Ramadan 1443
$date->subDays(3);                   // 28th Sha'ban 1443
$date2 = new HijriDate(1443, 8, 20); // 20th Sha'ban 1443
$date->diffInDays($date2);           // 8

比较

您可以使用以下方法比较两个HijriDate对象 $a 和 $b：

格式化

当创建HijriDate对象时，每个对象都会设置一个区域设置。此区域设置将用于格式化。

默认区域设置为 'dv'，但您可以通过以下方式自定义它：

在构造函数中传递区域设置（例如：new HijriDate(1443, 9, 1, 'en')）
创建后更改区域设置（例如：$date->setLocale('en')）
在配置中更改 default_locale，因此所有HijriDate对象都使用该默认区域设置创建

$date->format() 支持以下选项：

$date = new HijriDate(1443, 9, 1);  // 1st Ramadan 1443
$date->format("F");                 // "ރަމަޟާން" (using default locale 'dv')

$date->setLocale('ar');
$date->format("F Y");               // "رمضان 1443"
// Use numerals from locale
$date->format("F Y", true);         // "رمضان ١٤٤٣"

类型转换

要转换的字段必须是数据库上的字符串字段。

// App/Models/YourModel.php

class YourModel
{
    ...

    protected $casts = [
        ...
        'your_hijri_date_field' => HijriDate::class,
    ];
}

这将自动将数据存储为数据库中的 Y-m-d 字符串，并在访问时转换为 Remls\HijriDate\HijriDate。

验证

任何满足以下条件的字符串都被认为是有效的Hijri日期：

格式为 Y-m-d
年份介于1000和1999之间（此值可以在配置中更改）
月份介于1和12之间
日期介于1和30之间

use Remls\HijriDate\Rules\ValidHijriDate;

...
request()->validate([
    'your_hijri_date_field' => ['required', new ValidHijriDate],
]);

请注意，验证错误消息将使用应用程序的区域设置（与格式化不同）。

本地化

使用以下方式发布翻译文件：

php artisan vendor:publish --provider="Remls\HijriDate\HijriDateServiceProvider" --tag="lang"

然后根据需要自定义字符串。

添加语言

要添加对其他语言的支持

发布配置文件。该文件将被复制到 config/hijri.php。
发布翻译文件。文件将被复制到 lang/vendor/hijri。
复制现有的翻译文件夹之一，并使用您选择的语言代码将其重命名。例如：lang/vendor/hijri/es
将字符串更改为其相应的翻译。
在config/hijri.php中向supported_locales添加语言代码。
（可选）将config/hijri.php中的default_locale更改为新语言代码。

从v1迁移到v2

默认情况下，该软件包不再使用估计值来从伊斯兰历转换为公历。

在config/hijri.php中添加了新的键。您可能需要更新配置文件。
函数getEstimateFromGregorian已被移除，以支持新的函数createFromGregorian。
- 为了保持与之前相同的行为
  1. 将config/hijri.php中的conversion.converter更改为\Remls\HijriDate\Converters\MaldivesEstimateG2HConverter::class。
  2. 将所有对getEstimateFromGregorian的调用更改为createFromGregorian。
函数isEstimate已被移除。由于现在您可以通过调用getGregorianDate始终获取相应的公历日期，因此不再需要检查日期是否由估计值创建。
函数getEstimatedFrom已被移除，以支持新的函数getGregorianDate。
函数resetEstimation已被移除，以支持新的函数resetGregorianDate。
函数addDays和subDays将默认使用底层公历日期进行计算。
- 为了保持与之前相同的行为，请将这些函数的$useGregorian参数传递为false。

remls / hijri-date

维护者

详细信息