PHPackages                             hananils/kirby-date-methods - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. hananils/kirby-date-methods

ActiveKirby-plugin[Utility & Helpers](/categories/utility)

hananils/kirby-date-methods
===========================

Parsing and formatting dates can be difficult, especially if you deal with multilingual content. Date Methods aims to simplify date output by providing page and field methods to handle points in time as well as date ranges accurately in your snippets and templates.

3.2.0(3mo ago)298192MITPHPPHP ^8.2

Since Jun 23Pushed 3mo ago4 watchersCompare

[ Source](https://github.com/hananils/kirby-date-methods)[ Packagist](https://packagist.org/packages/hananils/kirby-date-methods)[ Docs](https://kirby.hananils.de/plugins/date-methods)[ RSS](/packages/hananils-kirby-date-methods/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (9)Dependencies (2)Versions (7)Used By (0)

[![Kirby Date Methods](.github/title.png)](.github/title.png)

Date Methods is a plugin for [Kirby](https://getkirby.com) 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.

Note

Please check out the online documentation at [kirby.hananils.de/plugins/date-methods](https://kirby.hananils.de/plugins/date-methods) for further information.

Overview
--------

[](#overview)

There are four types of methods:

### 1. Converters

[](#1-converters)

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

- [`toDateTime()`](#todatetime) or [`datetime()`](#datetimedatetime)
- [`toDateTimeImmutable()`](#todatetimeimmutable)
- [`toDateInterval()`](#todateinterval)
- [`toDateDiff()`](#todatediffto)
- [`toDatePeriod()`](#todateperiodfieldstart-fieldend-interval)
- [`toDates()`](#todatesfieldstart-fieldend-interval-format)

```
// 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. Formatters

[](#2-formatters)

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

- [`toFormatted()`](#toformatteddatetype-timetype-timezone-calendar-pattern) or [`dateFormatted()`](#dateformattedlocale-datetime-datetype-timetype-timezone-calendar-pattern)
- [`toFormattedPattern()`](#toformattedpatternpattern)
- [`toRelative()`](#torelativefrom) or [`dateRelative()`](#daterelativeto-from-locale)
- [`toTime()`](#totimeformat)
- [`toAge()`](#toageon-format)
- [`toDateRange()`](#todaterangefieldstart-fieldend) or [`dateRange()`](#daterangeto-from)

```
// 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. Modifiers

[](#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.

- [`toDateRounded()`](#todateroundedinterval-reference) or [`dateRounded()`](#dateroundeddatetime-interval-reference)
- [`toCurrentYear()`](#tocurrentyear)
- [`toCurrentMonth()`](#tocurrentmonth)
- [`toCurrentDay()`](#tocurrentday)
- [`normalizeDate()`](#normalizedatestring)
- [`normalizeTime()`](#normalizetimestring)

```
// 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();
```

### 4. Validators

[](#4-validators)

- [`isEarlierThan()`](#isearlierthandate-equal)
- [`isLaterThan()`](#islaterthandate-equal)

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

Installation
------------

[](#installation)

### Download

[](#download)

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

### Git submodule

[](#git-submodule)

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

```

### Composer

[](#composer)

```
composer require hananils/kirby-date-methods

```

Field methods
=============

[](#field-methods)

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

toDateTime()
------------

[](#todatetime)

Returns a `DateTime` representation of the field value, see [supported formats](https://www.php.net/manual/en/datetime.formats.php).

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

toDateTimeImmutable()
---------------------

[](#todatetimeimmutable)

Returns a `DateTimeImmutable` representation of the field value, see [supported formats](https://www.php.net/manual/en/datetime.formats.php).

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

toDateInterval()
----------------

[](#todateinterval)

Returns a `DateInterval` representation of the field value, see [supported formats](https://www.php.net/manual/en/dateinterval.construct.php).

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

toDateDiff($to)
---------------

[](#todatediffto)

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```.

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

toDateRounded($interval, $reference)
------------------------------------

[](#todateroundedinterval-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)
-----------------------------------------------------------------

[](#toformatteddatetype-timetype-timezone-calendar-pattern)

Returns a localized, formatted date using `IntlDateFormatter`, see [options](https://www.php.net/manual/de/intldateformatter.create.php).

- **`$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 `''`.

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

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

toFormattedPattern($pattern)
----------------------------

[](#toformattedpatternpattern)

Returns a localized date formatted by the given pattern, see [symbol table](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) for reference. Shortcut to `toFormatted`.

- **`$pattern`:** the pattern, defaults to `MMMM y`.

toRelative($from)
-----------------

[](#torelativefrom)

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](https://www.php.net/manual/en/datetime.formats.php).

- **`$from`:** the reference date to compare the field value to, defaults to `now`.

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

toTime($format)
---------------

[](#totimeformat)

Returns the formatted time of the given field value.

- **`$format`:** the time format, defaults to `H:i`.

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

toCurrentYear()
---------------

[](#tocurrentyear)

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

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

toCurrentMonth()
----------------

[](#tocurrentmonth)

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

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

toCurrentDay()
--------------

[](#tocurrentday)

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

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

toAge($on, $format)
-------------------

[](#toageon-format)

Calculates the difference difference between the field value and the given date. Returns the difference in the given format, see [format options](https://www.php.net/manual/de/dateinterval.format.php). 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).

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

isEarlierThan($date, $equal)
----------------------------

[](#isearlierthandate-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)
--------------------------

[](#islaterthandate-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
=============

[](#pages-methods)

toDateRange($fieldStart, $fieldEnd)
-----------------------------------

[](#todaterangefieldstart-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](https://github.com/flack/ranger).

toDatePeriod($fieldStart, $fieldEnd, $interval)
-----------------------------------------------

[](#todateperiodfieldstart-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)
---------------------------------------------------

[](#todatesfieldstart-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
=======

[](#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)
-------------------

[](#datetimedatetime)

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)
---------------------------------

[](#daterelativeto-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](https://www.php.net/manual/en/datetime.formats.php).

- **`$to`:** the date to compare to.
- **`$from`:** the date to compare from, defaults to `now`.
- **`$locale`:** the locale used for formatting.

```
dateRelative('2019-12-31', 'now');
```

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

[](#dateformattedlocale-datetime-datetype-timetype-timezone-calendar-pattern)

Returns a localized, formatted date using `IntlDateFormatter`, see [options](https://www.php.net/manual/de/intldateformatter.create.php).

- **`$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 `''`.

```
dateFormatted('de_DE', '2020-01-01');
```

dateRounded($datetime, $interval, $reference)
---------------------------------------------

[](#dateroundeddatetime-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)
---------------------

[](#daterangeto-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'\].

```
dateRange('2020-01-01', '2020-07-01');
```

The formatting is provided by [Ranger](https://github.com/flack/ranger).

normalizeDate($string)
----------------------

[](#normalizedatestring)

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

- **`$string`:** the date string to be normalized.

normalizeTime($string)
----------------------

[](#normalizetimestring)

Converts the given date string to `H:i` format.

- **`$string`:** the date string to be normalized.

Options
=======

[](#options)

There are several options to customize the plugin behaviour:

optiondescriptiondefault`code`The locale`de``rangeseparator`The string used to separate a date range, e.g. `01.08.–05.08.24``–``datetimeseparator`The string used to separate date and time, e.g. `01.08., 10:00``, ``datetype`The date format used.
Must be one of [the predefined constants in IntlDateFormatter](https://www.php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.full)`IntlDateFormatter::LONG``timetype`The time format used.
Must be one of [the predefined constants in IntlDateFormatter](https://www.php.net/manual/en/class.intldateformatter.php#intldateformatter.constants.full)`IntlDateFormatter::SHORT`License
=======

[](#license)

This plugin is provided freely under the [MIT license](LICENSE.md) by [hana+nils · Büro für Gestaltung](https://hananils.de). We create visual designs for digital and analog media.

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance81

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 97.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~418 days

Recently: every ~413 days

Total

6

Last Release

99d ago

Major Versions

1.0.0 → 2.0.02021-09-06

2.1.0 → 3.0.02025-06-25

### Community

Maintainers

![](https://www.gravatar.com/avatar/e0465cfa7ef2b9a264429068ddfeb765f3881f9c611048d2e7e95dfad4afbb35?d=identicon)[hananils](/maintainers/hananils)

---

Top Contributors

[![nilshoerrmann](https://avatars.githubusercontent.com/u/25466?v=4)](https://github.com/nilshoerrmann "nilshoerrmann (42 commits)")[![bezin](https://avatars.githubusercontent.com/u/4400435?v=4)](https://github.com/bezin "bezin (1 commits)")

---

Tags

kirby3-plugin

### Embed Badge

![Health badge](/badges/hananils-kirby-date-methods/health.svg)

```
[![Health](https://phpackages.com/badges/hananils-kirby-date-methods/health.svg)](https://phpackages.com/packages/hananils-kirby-date-methods)
```

###  Alternatives

[medienbaecker/kirby-modules

Easily add modules to your pages

895.4k1](/packages/medienbaecker-kirby-modules)[distantnative/retour-for-kirby

Manage redirects and track 404s right from the Kirby CMS Panel

14695.1k1](/packages/distantnative-retour-for-kirby)[arnoson/kirby-vite

Vite helper for Kirby CMS

9763.1k3](/packages/arnoson-kirby-vite)[belugadigital/kirby-navigation

Kirby 5 field for hierarchical menus with drag & drop level indentation.

8613.8k](/packages/belugadigital-kirby-navigation)[bnomei/kirby3-dotenv

Kirby Plugin for environment variables from .env

4147.7k1](/packages/bnomei-kirby3-dotenv)[fabianmichael/kirby-meta

Your all-in-one powerhouse for any SEO and metadata needs imaginable.

7011.3k1](/packages/fabianmichael-kirby-meta)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)