Download the PHP package hananils/kirby-date-methods without Composer

Date Methods is a plugin for Kirby 3 that allows for advanced date and time parsing and formatting using PHP's core date objects. It offers methods for fields to handle single dates, methods for pages to handle multiple dates (ranges) and also provides helper functions to simplify working with dates and times in general.

Overview

There are four types of methods:

1. Converters

Converters read a date string and convert it to PHP date and time objects like DateTime, DateTimeImmutable or DateInterval or arrays.

• datetime()
• toDateTimeImmutable()
• toDateInterval()
• toDateDiff()
• toDatePeriod()
• toDates()

2. Formatters

Formatters read a date string and return a formatted and localized string, either absolute or relative.

• dateFormatted()
• toFormattedPattern()
• dateRelative()
• toTime()
• toAge()
• dateRange()

3. Modifiers

Modifiers adjust dates to the current day, month or year which is helpful when you need to display the birthday of a person this year.

• dateRounded()
• toCurrentYear()
• toCurrentMonth()
• toCurrentDay()
• normalizeDate()
• normalizeTime()

4. Validators

• isEarlierThan()
• isLaterThan()

Installation

Download

Download and copy this repository to /site/plugins/date-methods.

Git submodule

Composer

Field methods

Field methods can be called on any field storing date information in a PHP-readable format.

toDateTime()

Returns a DateTime representation of the field value, see supported formats.

toDateTimeImmutable()

Returns a DateTimeImmutable representation of the field value, see supported formats.

toDateInterval()

Returns a DateInterval representation of the field value, see supported formats.

toDateDiff($to)

Returns a DateInterval object representing the difference between the field's date and the given date. The provided date can either be a DateTime object or a PHP-readable string, defaults to the difference to now.

• $to: date to compare the field value with. The provided date can either be a DateTime object or a PHP-readable string, defaults to `now```.

toDateRounded($interval, $reference)

Returns a DateTime representation of the field's value rounded the given interval.

• $interval: the interval to round the date to, defaults to 5 minutes (PT5M).
• $reference: reference date to start the interval from. Defaults to the beginning of the century for year intervals, to the first day of the year for month intervals, to the first day of the current month for day intervals and to midnight for all smaller intervals.

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

Returns a localized, formatted date using IntlDateFormatter, see options.

• $datetype: the datetype, defaults to IntlDateFormatter::LONG.
• $timetype: the timetype, defaults to IntlDateFormatter::NONE.
• $timezone: the timezone, defaults to null.
• $calendar: the calendar, defaults to null.
• $pattern: the pattern, defaults to ''.

The locale is set based on the current Kirby language in a multilangual setup or on the locale config setting otherwise.

toFormattedPattern($pattern)

Returns a localized date formatted by the given pattern, see symbol table for reference. Shortcut to toFormatted.

• $pattern: the pattern, defaults to MMMM y.

toRelative($from)

Returns a human readable time difference to the given date, e. g. just now, 2 years ago, in 5 minutes. The given date can be a DateTime object or any PHP-readable date string, see supported formats.

• $from: the reference date to compare the field value to, defaults to now.

toTime($format)

Returns the formatted time of the given field value.

• $format: the time format, defaults to H:i.

toCurrentYear()

Creates a DateTime representation of the field value and returns it with the year set to the current one.

toCurrentMonth()

Creates a DateTime representation of the field value and returns it with the month set to the current one.

toCurrentDay()

Creates a DateTime representation of the field value and returns it with the day set to the current one.

toAge($on, $format)

Calculates the difference difference between the field value and the given date. Returns the difference in the given format, see format options. Useful to calculate the age of a person.

• $on: reference date for the age calculation, defaults to today.
• $format: age format, defaults to %y (years).

isEarlierThan($date, $equal)

Checks it the field value is earlier than or equal to the given date.

• $date: the reference date, defaults to now.
• $equal: flag to also accept equal dates, defaults to false.

IsLaterThan($date, $equal)

Checks it the field value is later than or equal to the given date.

• $date: the reference date, defaults to now.
• $equal: flag to also accept equal dates, defaults to false.

Pages methods

toDateRange($fieldStart, $fieldEnd)

Returns a human-readable date range for the given dates:

• $fieldStart: the start date field name, defaults to 'start'.
• $fieldEnd: the end date field name, defaults to 'end'.

Returns a human-readable date range for the given dates and times:

• $fieldStart: an array of the start date and time field names, defaults to ['start', 'starttime'].
• $fieldEnd: the end date and time field names, defaults to ['end', 'endtime'].

The formatting is provided by Ranger.

toDatePeriod($fieldStart, $fieldEnd, $interval)

Returns a DatePeriod object for the values of the given fields and interval.

• $fieldStart: the start date field name, defaults to 'start'.
• $fieldEnd: the end date field name, defaults to 'end'.
• $interval: the interval used for the period, defaults to P1D (one day).

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

Returns the dates of the period for the values of the given fields and interval.

• $fieldStart: the start date field name, defaults to 'start'.
• $fieldEnd: the end date field name, defaults to 'end'.
• $interval: the interval used for the period, defaults to P1D (one day).
• $format: the format used for the returned dates, defaults to Y-m-d.

Helpers

These helpers are used under the hood of the field and page methods and can be used outside of the field or pages context by passing date strings.

datetime($datetime)

Returns a DateTime object from the given date and time string. Directly returns the input if it's a DateTime object already.

-$datetime: the date, defaults to now.

dateRelative($to, $from, $locale)

Returns a human readable time difference to the given date, e. g. just now, 2 years ago, in 5 minutes. The given date can be a DateTime object or any PHP-readable date string, see supported formats.

• $to: the date to compare to.
• $from: the date to compare from, defaults to now.
• $locale: the locale used for formatting.

dateFormatted($locale, $datetime, $datetype, $timetype, $timezone, $calendar, $pattern)

Returns a localized, formatted date using IntlDateFormatter, see options.

• $locale: the locale used for formatting.
• $datetime: the date in a PHP readable format.
• $datetype: the datetype, defaults to IntlDateFormatter::LONG.
• $timetype: the timetype, defaults to IntlDateFormatter::NONE.
• $timezone: the timezone, defaults to null.
• $calendar: the calendar, defaults to null.
• $pattern: the pattern, defaults to ''.

dateRounded($datetime, $interval, $reference)

Returns a DateTime representation of the field's value rounded the given interval.

• $datetime: the date in a PHP readable format.
• $interval: the interval to round the date to, defaults to 5 minutes (PT5M).
• $reference: reference date to start the interval from. Defaults to the beginning of the century for year intervals, to the first day of the year for month intervals, to the first day of the current month for day intervals and to midnight for all smaller intervals.

dateRange($to, $from)

Returns a human-readable date range for the given dates and times:

• $to: an array of the start date and time field names, defaults to ['start', 'starttime'].
• $from: the end date and time field names, defaults to ['end', 'endtime'].

The formatting is provided by Ranger.

normalizeDate($string)

Converts the given date string to Y-m-d format.

• $string: the date string to be normalized.

normalizeTime($string)

Converts the given date string to H:i format.

• $string: the date string to be normalized.

Options

There are several options to customize the plugin behaviour:

License

This plugin is provided freely under the hana+nils · Büro für Gestaltung. We create visual designs for digital and analog media.