README

💿 composer require dakujem/time

📒 变更日志

一个不罗嗦的时间处理库，以简单的方式执行时间计算。

时间工具包 的目的是帮助处理像工作计时测量、时间表、日历、订阅计时器等时间数据。

例如，Time 支持处理 负时间 和超过 24 小时的 时间，与 DateTime 或 Carbon 不同。

// negative time values
(string) Time::create('-10:30'); // -10:30:00
(string) Time::create('10:30')->subHours(100); // -89:30:00

// time values exceeding 24 hours
Time::create('50:00:00'); // 50 hours
Time::fromDays(10); // 10 days

与 DateTime 或 Carbon (nesbot/carbon) 相反，Time 仅仅是秒数的时间容器，它不指向任何实际的时刻，没有时区，也没有其他。

使用 Time，您可以 比较 时间值，执行 算术运算 或 转换 它们。您还可以解析包含格式化时间值的字符串，并按指定 格式 打印 Time 对象。

您的数据可能以秒、分钟、小时或格式化的字符串存储，使用 Time 处理仍然相同。

方法

有许多方法用于 处理、转换、修改、读取 和 打印 时间值。

创建时间对象的选项

// constructor, create, fromSeconds, fromMinutes, fromHours, fromDays, fromWeeks
new Time('12:20') == Time::create('12:20')
Time::fromDays(4)
Time::fromHours(12, 20) == Time::create('12:20') == Time::create(44400) == Time::fromSeconds(44400)

算术方法

// arithmetic methods: add, sub, mult, div, mod
(new Time('12:00'))->add(Time::fromSeconds(17000))->sub(new Time(45))
Time::fromHours(10)->div(2) // 5 hours

比较

// comparison methods: lt, lte, gt, gte, eq, neq, between
(new Time('12:00'))->between('12:30', '11:30') // TRUE

添加或减去秒、分钟、小时、天或周

// adding values: addSeconds, addMinutes, addHours, addDays, addWeeks
// subtracting values: subSeconds, subMinutes, subHours, subDays, subWeeks
(string) Time::create(123) //  00:02:03
        ->addSeconds(10)   //  00:02:13
        ->addSeconds(-10)  //  00:02:03
        ->subMinutes(-10)  // -00:08:03

转换选项

// conversion options: toSeconds, toMinutes, toHours, toDays, toWeeks
Time::fromWeeks(4)->toSeconds() // 2419200
Time::fromDays(3.5)->toWeeks()  // 0.5

输入解析（读取）和输出格式化

// string time parsing (reading)
Time::create('23:59:59')->toSeconds() == TimeHelper::parse('23:59:59')
TimeHelper::parse('-10:30')
Time::create(TimeHelper::parse('10:30 PM', TimeHelper::FORMAT_HMA)) // custom format

// output formatting
(string) Time::create(123)->format(Time::FORMAT_HM); // 00:02 - custom format (HH:mm)
(string) Time::fromHours(2, 3, 4); // 02:03:04 - the default format (HH:mm:ss)

输出到其他时间对象（转换）

// converting to DateTime or Carbon: toDateTime, toCarbon
$carbon = Time::create(123)->toCarbon();
$datetm = Time::create('07:50 AM')->toDateTime();

验证有效日时间和剪切到有效日时间

// clipping to valid day time
Time::create(-1)->isValidDayTime(); // FALSE
(string) Time::create(-1); // -00:00:01
(string) Time::create(-1)->clipToDayTime(); // 23:59:59
(Time::create('23:59:59'))          // 23:59:59
        ->addSeconds(1)             // 24:00:00
        ->clipToDayTime();          // 00:00:00

还有更多！

注意：对于所有方法，请参阅 源代码。

可变和不可变时间对象

默认的 Time 对象是 不可变 的。这意味着一旦创建了一个 Time 实例，它的值就不会改变。任何修改都会返回一个新的实例。

$immutable = Time::fromSeconds(0);
// all the operations work as expected:
(string) $immutable->addSeconds(30)->mult(2); // "00:01:00"
// but the instance itself does not change - this is in contrast to the mutable TimeMutable object:
$immutable->getMinutes(); // 0

有时需要将时间对象作为 可变对象、累加器处理，解决方案是 TimeMutable 类。

$mutable = TimeMutable::fromSeconds(0);
(string) $mutable->addSeconds(30)->mult(2); // "00:01:00"
// the modifications are accumulated inside the TimeMutable instance:
$mutable->getMinutes(); // 1

TimeMutable 对于聚合可能很有用

$acc = new TimeMutable();
foreach(... as $foo){
    $acc->add($foo->getDuration());
}
print $acc;

解析时间字符串和格式化

默认情况下，Time 接受 HH:MM:SS 格式的时间字符串。

Time::create('23:59:59')->sub('12:30')

默认格式存储在静态变量 TimeHelper::$defaultFormat 中，可以更改。然而，使用工厂并将 Time 实例传递到计算中总是更灵活。

$timeFactory = new TimeFactory();
$timeFactory->create('23:59:59')->sub($timeFactory->create('12:30'))

这样，可以在运行时更改输入的格式，并且可以为所有工厂独立设置。工厂也可以以自定义方式实现并使用自定义解析器。

如果不使用工厂而要使用不同的格式，可以直接使用 TimeHelper。

Time::create(TimeHelper::parse('23:59:59'))->sub(TimeHelper::parse('10:30 PM', TimeHelper::FORMAT_HMA))

格式化也是同样的原理。将时间对象转换为字符串使用的是存储在 TimeHelper::$defaultFormat 中的格式，默认为 HH:MM:SS。

注意

不建议使用负数时解析和打印“有趣”的格式（如“i:H”，“?i:s”）。最好只解析标准时间表示。如果需要解析特殊的时间格式，应提供自己的解析器，之后使用 Time 库进行计算。

毫秒、微秒...

Time对象是为以秒为单位的计算而构建的，这是所有功能都正常工作的最大整数分辨率。

然而，可以使用double时间值以获得更高的分辨率（毫秒或微秒）

Time::create(5.500) // 5.5 seconds

在使用双精度浮点数时，以下功能（尚未）正确工作

• 解析 - 需要自定义解析
• 格式化 - 当前TimeHelper无法正确格式化双精度浮点数
• 尚未实现四舍五入或绝对值

注意：当使用双精度浮点数数据类型时，所有PHP实现限制都适用。

安装

使用Composer

$ composer require dakujem/time

测试

运行CLI命令

$ composer test

或者在浏览器中打开tests/index.php。