README

日期方法是一个为 Kirby 3 设计的插件，允许使用 PHP 的核心日期对象进行高级日期和时间解析和格式化。它为字段提供了处理单个日期的方法，为页面提供了处理多个日期（范围）的方法，并提供了一些辅助函数，以简化日期和时间的处理。

概述

有四种类型的方法

1. 转换器

转换器读取日期字符串并将其转换为 PHP 日期和时间对象，如 DateTime、DateTimeImmutable 或 DateInterval 或数组。

toDateTime() 或 datetime()
toDateTimeImmutable()
toDateInterval()
toDateDiff()
toDatePeriod()
toDates()

// Get DateTime object
$datetime = $page->date()->toDateTime();

// Modify and format date
$page
  ->date()
  ->toDateTime()
  ->modify('+1 month')
  ->format('Y-m-d');

// Compare a date field to another date
$page
  ->date()
  ->toDateDiff('2000-01-01')
  ->format('The beginning of the century was %y ago.');

2. 格式化器

格式化器读取日期字符串并返回格式化和本地化的字符串，无论是绝对的还是相对的。

toFormatted() 或 dateFormatted()
toFormattedPattern()
toRelative() 或 dateRelative()
toTime()
toAge()
toDateRange() 或 dateRange()

// Get the date formatted in the current locale style, e. g.
// '2021-01-01' becomes '1. Januar 2021' in German
echo $page->date()->toFormatted();

// Get the date formatted with a specific pattern in the current
// locale style, e. g. '2021-01-01' becomes 'Januar 2021'
echo $page->date()->toFormattedPattern('MMMM y');

// Get the relative date like '5 days ago'
echo $page->date()->toRelative();

// Get the age of a person
echo 'Nils is now ' . $page->birthday()->toAge() . ' years old';

// Given a start and an end date field, return the localized
// formatted date range, e. g. for the field values '2021-07-17'
// and '2021-07-21' return '17. – 21. Juli 2021'
echo $page->toDateRange();

3. 修饰器

修饰器将日期调整到当前日、月或年，这在需要显示今年某人的生日时非常有用。

toDateRounded() 或 dateRounded()
toCurrentYear()
toCurrentMonth()
toCurrentDay()
normalizeDate()
normalizeTime()

// Round a date to the next full 5 minutes, e. g.
// '2021-02-01 13:42' becomes '2021-02-01 13:45'
$published = $page->published()->toDateRounded();

// This can then be formatted automatically, e. g.
// '1. Februar 2021 13:45'
$published->toFormatted(IntlDateFormatter::LONG, IntlDateFormatter::SHORT);

// Get a user's birthday this year
echo 'Bastian’s birthday is on ' .
  $user
    ->birthday()
    ->toCurrentYear()
    ->toFormatted();

// Check the given date
if ($page->published()->isEarlierThan('2010-01-01')) {
  echo 'This article is very old, please check if there are update available.'
}

安装

下载

下载并将此存储库复制到 /site/plugins/date-methods。

Git 子模块

git submodule add https://github.com/hananils/kirby-date-methods.git site/plugins/date-methods

Composer

composer require hananils/kirby-date-methods

字段方法

字段方法可以用于任何存储日期信息的 PHP 读取格式的字段。

toDateTime()

返回字段的 DateTime 表示形式，请参阅支持格式。

$page->date()->toDateTime();

toDateTimeImmutable()

返回字段的 DateTimeImmutable 表示形式，请参阅支持格式。

$page->date()->toDateTimeImmutable();

toDateInterval()

返回字段的 DateInterval 表示形式，请参阅支持格式。

$page->date()->toDateInterval();

toDateDiff($to)

返回一个表示字段日期与给定日期之间差异的 DateInterval 对象。提供的日期可以是 DateTime 对象或 PHP 可读取的字符串，默认为现在的时间。

$to: 与字段值进行比较的日期。提供的日期可以是 DateTime 对象或 PHP 可读取的字符串，默认为 `now`。

$page->date()->toDateDiff('+1 month');

toDateRounded($interval, $reference)

返回一个将日期四舍五入到给定间隔的 DateTime 表示形式。

$interval: 将日期四舍五入到的间隔，默认为 5 分钟 (PT5M)。
$reference: 区间开始日期的参考日期。对于年区间，默认为世纪开始，对于月区间，默认为年初，对于日区间，默认为当前月的第一天，对于所有更小的区间，默认为午夜。

toFormatted($datetype, $timetype, $timezone, $calendar, $pattern)

使用 IntlDateFormatter 返回本地化的、格式化的日期，请参阅选项。

$datetype: 日期类型，默认为 IntlDateFormatter::LONG。
$timetype: 时间类型，默认为 IntlDateFormatter::NONE。
$timezone: 时区，默认为 null。
$calendar: 日历，默认为 null。
$pattern: 模式，默认为 ''。

// Returns 1. Januar 2020 for 2020-01-01 and de_DE
$page->date()->toFormatted();

在多语言设置中，语言设置为当前 Kirby 语言或否则的 locale 配置设置。

toFormattedPattern($pattern)

使用给定模式返回本地化的日期格式，请参阅符号表以获取参考。是 toFormatted 的快捷方式。

$pattern: 模式，默认为 MMMM y。

toRelative($from)

返回给定日期的可读时间差，例如 刚刚、2年前、5分钟后。给定的日期可以是 DateTime 对象或任何 PHP 可读日期字符串，请参阅支持格式。

$from: 比较字段值的参考日期，默认为 now。

$page->date()->toRelative('next Monday');

toTime($format)

返回给定字段值的格式化时间。

$format: 时间格式，默认为 H:i。

$page->date()->toTime();

toCurrentYear()

创建字段值的 DateTime 表示并返回它，年份设置为当前年份。

$page->date()->toCurrentYear();

toCurrentMonth()

创建字段值的 DateTime 表示并返回它，月份设置为当前月份。

$page->date()->toCurrentMonth();

toCurrentDay()

创建字段值的 DateTime 表示并返回它，日期设置为当前日期。

$page->date()->toCurrentDay();

toAge($on, $format)

计算字段值与给定日期之间的差异。以给定格式返回差异，请参阅格式选项。用于计算人的年龄非常有用。

$on: 年龄计算的参考日期，默认为 today。
$format: 年龄格式，默认为 %y（年）。

// Returns 10 given '2011-08-04'
$page->date()->toAge('2021-08-04');

isEarlierThan($date, $equal)

检查字段值是否早于或等于给定日期。

$date: 参考日期，默认为 now。
$equal: 标志，用于接受相等日期，默认为 false。

IsLaterThan($date, $equal)

检查字段值是否晚于或等于给定日期。

$date: 参考日期，默认为 now。
$equal: 标志，用于接受相等日期，默认为 false。

页面方法

toDateRange($fieldStart, $fieldEnd)

返回给定日期的人读日期范围。

$fieldStart: 开始日期字段名称，默认为 'start'。
$fieldEnd: 结束日期字段名称，默认为 'end'。

返回给定日期和时间的可读日期范围。

$fieldStart: 开始日期和时间的字段名称数组，默认为 ['start', 'starttime']。
$fieldEnd: 结束日期和时间的字段名称，默认为 ['end', 'endtime']。

格式由 Ranger 提供。

toDatePeriod($fieldStart, $fieldEnd, $interval)

返回给定字段值和间隔的 DatePeriod 对象。

$fieldStart: 开始日期字段名称，默认为 'start'。
$fieldEnd: 结束日期字段名称，默认为 'end'。
$interval: 期间使用的间隔，默认为 P1D（一天）。

toDates($fieldStart, $fieldEnd, $interval, $format)

返回给定字段和间隔值的时间段日期。

$fieldStart: 开始日期字段名称，默认为 'start'。
$fieldEnd: 结束日期字段名称，默认为 'end'。
$interval: 期间使用的间隔，默认为 P1D（一天）。
$format: 返回日期使用的格式，默认为 Y-m-d。

辅助函数

这些辅助函数在字段和页面方法的后台使用，可以通过传递日期字符串在字段或页面上下文外使用。

datetime($datetime)

从给定的日期时间字符串返回一个 DateTime 对象。如果输入已经是 DateTime 对象，则直接返回。

-$datetime: 日期，默认为 now。

dateRelative($to, $from, $locale)