README

一个不可变的类，用于处理在 Noxem 系统中使用的 DateTime 对象。与 nette/forms 中的日期、日期时间表单字段完美配合。

PHP 8.2 已准备!!

要求

此库需要 PHP 8.1 或更高版本。

用法

Noxem\DateTime\DT

DT 对象的基本初始化。DT 对象是原生 DateTimeImmutable 对象的子类，具有修改日期/时间部分的句柄。

use Noxem\DateTime\DT;
use DateTime as NativeDateTime; 

DT::create('now'); // 2022-08-07 12:00:00
(new DT('now')); // 2022-08-07 12:00:00
DT::create(1659866400); // 2022-08-07 12:00:00 initialize with timestamp

DT::create('2022-08-07 12:00:00'); // 2022-08-07 12:00:00
DT::createFromParts(2022, 8, 7, 12); // 2022-08-07 12:00:00
DT::createFromFormat(); // PHP's native method
DT::createFromInterface(new NativeDateTime()); 
DT::fromUTC("2022-08-07T12:00:00Z"); // 2022-08-07 14:00:00 in Europe/Prague

DT::getOrCreateInstance("2022-08-07 12:00:00"); // 2022-08-07 12:00:00
DT::getOrCreateInstance(DT::create("2022-08-08 12:00:00")); // 2022-08-08 12:00:00

$dt = DT::create('now'); // 2022-08-07 12:00:00
$dt->modify('+5 seconds'); // 2022-08-07 12:00:05
$dt->addDays(1); // 2022-08-08 12:00:00
$dt->subDays(1); // 2022-08-06 12:00:00
$dt->modifyDays(1); // ekvivalent to addDays(1)

库支持将对象转换为 HTML 的原生输入类型

use Noxem\DateTime\DT;

$object = DT::create('2022-08-07 12:00:00');
$object->toHtmlDate(); // 2022-08-07
$object->toHtmlMonth(); // 2022-08
$object->toHtmlWeek(); // 2022-W31
$object->toHtmlYear(); // 2022

比较

DT::create('2022-08-07 12:00:00')
    ->areEquals(
        DT::create('2022-08-07 12:00:00')
        ->setTimezone('America/New_York')
    ); // FALSE

$ny = DT::create("2020-09-17 07:00:00")->assignTimezone("America/New_York");
$tokyo = DT::create("2020-09-17 20:00:00")->assignTimezone("Asia/Tokyo");
$ny->areEquals($tokyo); // TRUE

isFuture(): bool 我们操作的是未来吗？

$dt = DT::create('now');
echo $dt->modify('+1 seconds')->isFuture(); // TRUE
echo $dt->isFuture(); // FALSE

Noxem\DateTime\Difference

差异公式可以想象为 x = a - b，其中 a 是调用子方法的对象，公式示例是 x = $b->difference($a) 差异类可以通过方法 DT::create()->difference(DT $suspect) 访问。

$bigger = DT::create('2022-05-20 11:45:00');
$smaller = DT::create('2022-05-13 11:45:00');

$dt = $smaller->difference($bigger);
echo $dt->hours(); // 168.0
echo $dt->days(); // 7
echo $dt->solidWeeks(); // 1
echo $dt->minutes(); // 1440.0
echo $dt->msec(); // 86400000

$dt = $bigger->difference($smaller);
echo $dt->hours(); // -168.0
echo $dt->days(); // -7
echo $dt->solidWeeks(); // -1
echo $dt->minutes(); // -1440.0
echo $dt->msec(); // -86400000

类输出为有符号数字。其中：正数表示未来，负数表示回到未来。

方法 withAbsolute() 忽略方法中的负数，差异始终为正数

$first = DT::create('2022-05-20 11:45:00');
$last = DT::create('2022-05-13 11:45:00');

$dt = $first->difference($last);
echo $dt->hours(); // -168.0
echo $dt->withAbsolute()->hours(); // +168.0

该方法也是不可变的。

Noxem\DateTime\Overlap

下一个方法用于比较两个对象是否重叠。

use Noxem\DateTime\Overlapping;

Overlapping::withTouching(
    DT::create('2021-05-06 09:00:00'),
    DT::create('2021-05-06 10:00:00'),
    DT::create('2021-05-06 10:00:00'),
    DT::create('2021-05-06 13:00:00'),
); // FALSE

重叠类仅处理一个方法（将来数量将增加）。区间重叠语句的描述如下表所示

异常

错误的 DateTime 格式抛出一个继承自 InvalidArgumentException 的异常

use Noxem\DateTime\DT;
use Noxem\DateTime\Exception\BadFormatException;

$dt = DT::create('foo'); // BadFormatException