Verta完全指南：Laravel波斯历（Jalali）日期转换库从零入门

【免费下载链接】verta تبدیل تاریخ میلادی به شمسی برای لاراول و کار با تاریخ جلالی و اعتبارسنجی تاریخ 项目地址: https://gitcode.com/gh_mirrors/ve/verta

在开发面向伊朗、阿富汗等波斯语地区的 Laravel 应用时，最大的痛点之一就是日期：当地普遍使用波斯历（Jalali / 伊朗历 / 夏姆斯历 Shamsi），而服务器和数据库默认都是公历（格里高利历）。Verta 正是解决这个问题的Laravel 波斯历日期转换库：它继承 PHP 原生 DateTime，并兼容流行的 Carbon 组件，让你用一行代码完成公历与波斯历（Jalali）之间的互相转换、格式化、计算与校验。本文将从安装到实战，带你从零入门这款由 Nasser Hekmati 开发、MIT 协议开源的日期神器。

一、Verta 是什么？Laravel 项目为什么需要它

简单说，Verta 是一个「波斯历时间扩展包」：它以波斯历为第一视角，同时保留与公历、Carbon 的双向通道。核心能力包括：

• 🗓️ 公历 ↔ 波斯历（Jalali）互相转换
• ⏰ 创建、读取、修改波斯历日期时间
• 🧮 日期加减、边界计算（周初/月末/年初）
• 📊 日期比较与时间差计算
• ✅ 内置 Laravel 表单校验规则（jdate、jdatetime 等）
• 🌍 多语言本地化，支持波斯数字等

整个包的代码非常精简，核心实现集中在两个文件里：

• 核心类：src/Verta.php —— 继承 Jalali 基类，提供 toCarbon() 等方法
• 全局辅助函数：src/helpers.php —— 提供 verta() 函数

如果你好奇它如何与 Laravel 集成，可以看看 src/Laravel/VertaServiceProvider.php 和 src/Laravel/JalaliValidator.php，前者注册服务与校验规则，后者实现全部校验逻辑。

二、环境要求与 Composer 一键安装步骤

安装前请确认你的环境满足 composer.json 中的要求：

依赖	版本要求
PHP	^8.0
Laravel / illuminate	8.0 ~ 12.0+
hekmatinasser/jalali	^8.2.3

安装只需一条命令，在项目根目录执行：

composer require hekmatinasser/verta

Verta 通过 Laravel 的自动包发现机制注册 VertaServiceProvider，无需手动配置；若你的项目关闭了自动发现，也可在 config/app.php 中手动添加：

'providers' => [
    Hekmatinasser\Verta\Laravel\VertaServiceProvider::class,
],
'aliases' => [
    'Verta' => Hekmatinasser\Verta\Verta::class,
],

💡 想直接看源码跑起来？可以 git clone https://gitcode.com/gh_mirrors/ve/verta 后参照 tests/ 目录下的测试用例学习用法。

三、最快上手：verta() 辅助函数创建波斯历时间

安装完成后，verta() 全局函数就是你的第一把钥匙，它会自动把当前时间转成波斯历：

echo verta(); // 1404-05-25 00:00:00

如果传入一个公历日期字符串，它也会自动转换：

echo verta('2025-08-16'); // 1404-05-25 00:00:00

传入字符串或时间戳即可完成公历转波斯历；反向操作同样简单，波斯历转公历用静态方法 parse() 加 datetime()：

echo Verta::parse('1404-05-25 14:12:32')->datetime(); // 2025-08-16 14:12:32

通过 Facade 调用

在 Laravel 中也可以使用 Facade 门面，类定义见 src/Facades/Verta.php：

use Hekmatinasser\Verta\Facades\Verta;
echo Verta::parse('1404/05/25')->format('Y/m/d');

四、与 Carbon 无缝互通：toCarbon() 与 toJalali()

这是 Verta 最讨喜的特性——和 Laravel 生态中的 Carbon 完全兼容：

• now()->toJalali()：把 Carbon 时间转为波斯历
• verta()->toCarbon()：把波斯历时间转回 Carbon

echo now()->toJalali();     // 1404-05-25 00:00:00
echo verta()->toCarbon();   // 2025-08-16 00:00:00

toCarbon() 方法定义在 src/Verta.php 第 17-20 行，而 toJalali() 宏则由 VertaServiceProvider 在 boot() 中注册。这意味着你可以在 Eloquent 模型、队列任务里自由切换两套历法，无需重写业务逻辑。

五、读取与修改波斯历时间：Getter 与 Setter

Verta 支持像属性一样直接读写年月日时分秒：

$v = verta();              // 1404-05-25 14:18:23
echo $v->year;             // 1404
echo $v->month;            // 5
$v->year = 1403;           // 修改年份
$v->setTimeString('12:25:45'); // 链式修改时间

还有 setDate、setMonth、addWeeks(3)、subMonths(2) 等一整套修改方法，日常业务中的“三个月后”“上周五”都能轻松表达。

六、波斯历日期格式化与人性化时间差

格式化是展示环节的重头戏，Verta 提供了丰富的方法：

echo verta()->format('Y.m.d');          // 1404.05.25
echo verta()->formatWord('l dS F');     // 波斯语完整写法
echo verta()->formatJalaliDatetime();   // 1404/05/25 14:12:25

其中 formatWord() 支持输出波斯语星期与月份名称，formatDifference() 则能把时间差转成“1 周前”这样人类可读的文本：

echo verta('-13 month')->formatDifference(); // 1 سال قبل

七、边界计算与日期比较

业务中常见的“本周开始”“本月最后一天”等需求，Verta 也内置了便捷方法：

echo verta()->startWeek(3);   // 以周三为一周起点
echo verta()->endMonth();
echo verta()->startYear();

比较运算同样顺手，支持 eq、gt、gte、lt、lte 等：

echo verta('+2 day')->gte('2025-08-16'); // 布尔值
echo verta('+13 day')->diffMonths('2025-08-16'); // 相差月数

八、Laravel 表单波斯历日期校验：jdate 系列规则

这是 Verta 让表单开发省心的地方。安装后自动注册了 16 条校验规则，全部实现在 JalaliValidator 中：

规则	作用
jdate / jdatetime	校验是否为合法波斯历日期 / 日期时间
jdate_equal / jdate_not_equal	日期是否等于 / 不等于指定值
jdate_after / jdate_before	日期是否晚于 / 早于指定值
jdate_after_equal / jdate_before_equal	含等于的边界比较
jdate_multi_format	支持多种输入格式

在 FormRequest 中直接使用：

'birthday' => ['required', 'jdate', 'jdate_before_equal:today'],
'meeting'  => ['required', 'jdatetime_after:1404/05/25 08:00:00'],

校验失败时，错误信息里的日期还会自动转换成当前本地化的波斯数字，细节非常贴心。更多测试样例可参考 tests/Laravel/JalaliValidatorTest.php。

九、本地化与数字转换

Verta 支持设置语言环境，影响格式化输出与错误信息：

Verta::setLocale('ar');   // 阿拉伯语
Verta::setLocale('en');   // 英语（默认）

配合 getMessages() 机制，错误信息中的数字会自动替换为波斯数字，适合需要展示本地化文案的场景。

十、总结与建议

Verta 用极简的 API 把「公历 ↔ 波斯历（Jalali）」的转换、格式化、计算与表单校验全部打包好，且与 Carbon 无缝兼容，是 Laravel 波斯语项目日期处理的高性价比之选。建议新手从 verta() 函数和 jdate 校验规则入手，再逐步探索格式化与边界计算。

🧭 快速回顾核心模块：

• 全局函数入口：src/helpers.php
• 核心类与 Carbon 桥接：src/Verta.php
• Laravel 服务注册：src/Laravel/VertaServiceProvider.php
• 表单校验实现：src/Laravel/JalaliValidator.php
• 安装与版本对应关系：README.md、composer.json

如果你正在为波斯语市场开发 Laravel 应用，现在就动手试试这个Laravel 波斯历日期转换库吧，它会让你的日期处理效率提升一个台阶！🚀

【免费下载链接】verta تبدیل تاریخ میلادی به شمسی برای لاراول و کار با تاریخ جلالی و اعتبارسنجی تاریخ 项目地址: https://gitcode.com/gh_mirrors/ve/verta