stella-maris/intl-daterange-formatter

Format a daterange using internationalized output

0.2.0 2025-10-29 15:02 UTC

Requires

• php: ^8.3
• ext-intl: *

Requires (Dev)

• phpunit/phpunit: ^12.4

MIT

• Andreas Heigl

README

This small library tries to ease printing of date-ranges.

Installation

The library is installed via composer using

composer require stella-maris/intl-daterange-formatter

Usage

You can then use the DateRange Formatter library by creating a DateRangeFormatter-instance, setting a format and a separator and then call format() on it with the start-date and the end date as parameters like this:

<?php
use StellaMaris\IntlDateRangeFormatter\DateRangeFormatter

	$tz = new DateTimeZone('America/Los_Angeles');
		$dateRange = new DateRangeFormatter('de_DE', IntlDateFormatter::MEDIUM, $tz, ' - ');

echo $dateRange->format(new \DateTimeImmutable('12.3.2025', $tz), new \DateTimeImmutable('13.4.2025', $tz));
// Will print: 12.03. - 13.04.2025
echo $dateRange->getDateRange(new \DateTimeImmutable('12.3.2025', $tz), new \DateTimeImmutable('13.3.2025', $tz));
// Will print: 12. - 13.03.2025

More complex example:

<?php
use StellaMaris\IntlDateRangeFormatter\DateRangeFormatter

$tz = new DateTimeZone('America/Los_Angeles');
$dateRange = new DateRangeFormatter('en_US', IntlDateFormatter::MEDIUM, $tz, ' - ');

echo $dateRange->format(new \DateTimeImmutable('12.3.2025', $tz), new \DateTimeImmutable('13.4.2025', $tz));
// Will print: Mar 12,  - Apr 13, 2025
echo $dateRange->format(new \DateTimeImmutable('12.3.2025', $tz), new \DateTimeImmutable('13.3.2025', $tz));
// Will print: Mar 12,  - Mar 13, 2025

Filtering

The last example showed that there can be some unwanted characters in the formatting, like the , after the Mar 12 in the previous example.

You can remove them using Filters.

If you want to display the above string like Mar 12 - Mar 13, 2013 (note the missing , after the 12) you can add a RemoveEverythingAfterLastDateString Filter like this:

<?php
use StellaMaris\IntlDateRangeFormatter\DateRangeFormatter
use StellaMaris\IntlDateRangeFormatter\Filter\RemoveEverythingAfterLastDateString
use StellaMaris\IntlDateRangeFormatter\Filter
use StellaMaris\IntlDateRangeFormatter\FilterType

$filter = new Filter(new RemoveEverythingAfterLastDateString(), FilterType::FirstDiff);

$tz = new DateTimeZone('America/Los_Angeles');

$dateRange = new DateRangeFormatter('en_US', IntlDateFormatter::MEDIUM, $tz, ' - ', $filter);

echo $dateRange->format(new \DateTimeImmutable('12.3.2025', $tz), new \DateTimeImmutable('13.3.2025', $tz))
// Will print: Mar 12 - Mar 13, 2025

Currently the following Filters are available:

• RemoveEverythingAfterLastDateString - This filter will remove everything after the last dateformatting-character in the given date-part. So when the dateformatting-string reads d.m. it will remove everything behind the m which is the last dateformatting-character.
• TrimFilter - This filter will remove excess whitespace. It just passes the dateformatting-string through the `trim``-function.

You can implement your own filter by implementing the StellaMaris\IntlDateRangeFormatter\FilterInterface. That way evertything is possible!

You can add a filter to four different filterchains that filter different parts of the formatting string.

• FilterType::Complete will be applied to a formatting string when first and second day are the same. So the input will be the formatting-string you provided via the DateRangeFormatter::setFormat().
• FilterType::FirstDiff will be applied to the first part of the splitted formatting string that is used for the start-date. So when your formatting string is d.m.Y and the dates differ in the month the filter will be applied to d.m. for the starting date
• FilterType::SecondDiff will be applied to the first part of the splitted formatting string that is used for the end-date. So when your formatting-string is d.m.Y and the dates differ in the month the filter will be applied to d.m. for the end-date
• FilterType::Same will be applied to the second part of the splitted formatting string that is used for the part that is equal on start- and end-date. So when your formatting-string is d.m.Y and the dates differ in the day the filter will be applied to m.Y.

Date and Time-ranges

You can also format ranges based on date and time. Note though that the moment you want to include time in the range, there are three possibilities:

• The start and date timestamp are the same - Then only the start-date will be output fully formatted
• The start and end date are the same but not the time - Then the start-date will be fully formatted and the end-time will be appended
• The start and end date are not the same - Then the start-date as well as the end date will be fully formatted and combined with the provided string.

<?php
use StellaMaris\IntlDateRangeFormatter\DateTimeRangeFormatter
use StellaMaris\IntlDateRangeFormatter\Filter\RemoveEverythingAfterLastDateString
use StellaMaris\IntlDateRangeFormatter\Filter
use StellaMaris\IntlDateRangeFormatter\FilterType

$filter = new Filter(new RemoveEverythingAfterLastDateString(), FilterType::FirstDiff);

$tz = new DateTimeZone('America/Los_Angeles');

$dateRange = new DateTimeRangeFormatter('en_US', IntlDateFormatter::MEDIUM, IntlDateFormatter::MEDIUM, $tz, ' - ');

echo $dateRange->format(new \DateTimeImmutable('12.3.2025 12:23:34', $tz), new \DateTimeImmutable('13.3.2025 12:23:34', $tz));
// Will print: Mar 12, 2025, 12:23:34 PM - Mar 13, 2025, 12:23:34 PM'
echo $dateRange->format(new \DateTimeImmutable('12.3.2025 12:23:34', $tz), new \DateTimeImmutable('12.3.2025 13:23:34', $tz));
// Will print: Mar 12, 2025, 12:23:34 PM - 1:23:34 PM
echo $dateRange->format(new \DateTimeImmutable('12.3.2025 12:23:34', $tz), new \DateTimeImmutable('12.3.2025 12:23:34', $tz));
// Will print: Mar 12, 2025, 12:23:34 PM