openpsa / ranger

v0.6.2 2026-09-24 15:36 UTC

Requires

• php: >=7.0

Requires (Dev)

• phpunit/phpunit: >=6.5

Suggests

• ext-intl: Needed for usage with other locales than 'en'
• symfony/intl: Optional PHP alternative to ext-intl

MIT

• Andreas Flack

• time range
• date range

Published on Packagist.org on 2026-09-24 15:38 UTC

README

Ranger is a formatter for date and time ranges, based (somewhat loosely) on Adam Shaw's formatRange algorithm in fullCalendar.

Some Examples

<?php
use OpenPsa\Ranger\Ranger;

$ranger = new Ranger('en');
echo $ranger->format('2013-10-05', '2013-10-20');
// Oct 5–20, 2013
echo $ranger->format('2013-10-05', '2013-11-20');
// Oct 5 – Nov 20, 2013

$ranger = new Ranger('en_GB');
echo $ranger->format('2013-10-05', '2013-10-20');
// 5–20 Oct 2013
echo $ranger->format('2013-10-05', '2013-11-20');
// 5 Oct – 20 Nov 2013

$ranger = new Ranger('de');
echo $ranger->format('2013-10-05', '2013-10-20');
// 05.–20.10.2013
echo $ranger->format('2013-10-05', '2013-11-20');
// 05.10.–20.11.2013

Usage

To use Ranger, you will need to have the php-intl extension installed. If the you only need it to work in the "en" locale, you can alternatively require symfony/intl in your composer.json.

Instantiate ranger with the name of your locale as the parameter. You can also pass null to use the ini.default_locale setting. Afterwards, you can call format() with two date parameters. Accepted types are

• DateTime objects
• strings (any format that DateTime can read)
• Unix timestamps
• null (which means current date).

Output Customization

<?php
use OpenPsa\Ranger\Ranger;
use IntlDateFormatter;

$ranger = new Ranger('en');
$ranger
    ->setRangeSeparator(' and ')
    ->setDateTimeSeparator(', between ')
    ->setDateType(IntlDateFormatter::LONG)
    ->setTimeType(IntlDateFormatter::SHORT);

echo $ranger->format('2013-10-05 10:00:01', '2013-10-05 13:30:00');
// October 5, 2013, between 10:00 AM and 1:30 PM

Precision

If you don't need the full date, you can limit the precision (e.g. to Ranger::MONTH or Ranger::YEAR). Fields that are not displayed are ignored when comparing the two dates, and the resulting pattern is generated by ICU for the current locale and date type:

<?php
use OpenPsa\Ranger\Ranger;

$ranger = new Ranger('en');
$ranger->setPrecision(Ranger::MONTH);
echo $ranger->format('2020-01-08', '2020-10-26');
// Jan – Oct 2020
echo $ranger->format('2020-10-08', '2020-10-26');
// Oct 2020

$ranger->setPrecision(Ranger::YEAR);
echo $ranger->format('2015-03-01', '2020-06-01');
// 2015–2020

This requires IntlDatePatternGenerator, i.e. PHP 8.1+ with ext-intl. On older versions, setPrecision() throws a RuntimeException. Call setPrecision(null) to reset.