README

Simple Date Range Object for PHP 7.1|8.0

Earlier PHP versions: Check out the original DateRange by brtriver.

Requirements

PHP 7.1.0 or later

Install

Install using Composer:

$ composer require jasonjgardner/date-range

Usage

Creating date ranges

Create a date range object which contains a start \DateTime and an end \DateTime:

use jasonjgardner\DateRange\DateRange;
$summer = new DateRange('2017-06-20', '2017-09-22');

echo 'Summer starts on ', $summer->getStartDate()->format('F j, Y');
/// Summer starts on June 21, 2017

echo 'The last day of summer is ', $summer->getEndDate()->format('F j, Y');
/// The last day of summer is September 22, 2017

Pass a variety of variable types to the constructor:

/// Accepts `\DateTime` objects
new DateRange(new \DateTime('today'), new \DateTime('tomorrow'));

/// Accepts date strings
new DateRange('2017-09-15', '10-15-2017');

/// Accepts timestamps
$DateRange = new DateRange(1493886600, '1499172300');
echo $DateRange->toString('m/d/Y'); /// 05/04/2017 - 07/04/2017

/// Accepts an array of dates
$dates = [
	'2017-10-21',
	'2017-01-01',
	'2017-12-31',
	'2017-10-31'
];

$DateRange = new DateRange($dates);
echo $DateRange->getStartDate()->format('M j'); /// Jan 1
echo $DateRange->getEndDate()->format('M j'); /// Dec 31

/// Only requires a start date argument
$DateRange = new DateRange('12/31/2017');
echo $DateRange->getEndDate()->format('M j, Y G:i e'); /// Jan 1, 2018 0:00 UTC

/// Create dates in a certain timezone
$date = new \DateTime(
	'March 1, 2017 3:30 PM',
	new \DateTimeZone('America/New_York')
);

$DateRange = new DateRange(
	$date,
	null,
	new \DateTimeZone('Asia/Tokyo')
);

echo $DateRange->getStartDate()->format('M j, Y G:i e'); /// March 2, 2017 4:30 AM Asia/Tokyo

Date range comparisons

Check if a certain date comes before, after, or is during a date range:

$aries = new DateRange('March 21', 'April 19');
$birthday = new \DateTime('April 1');

if ($aries->compare($birthday) === 0) {
	echo 'You are an Aries ♈';
} else if ($aries->compare('March 1') < 0) {
	echo 'You look like a Pisces ♓';
} else if ($aries->compare('May 1') > 0) {
	echo 'Are you a Taurus? ♉';
}

The DateRange::compare() method compares a date string, object, or timestamp against the start and end dates in the date range. It will return -1 if the date is before the date range, 0 if the date is during the date range, or 1 if the date is after the date range.

The class constants DateRange::COMPARE_BEFORE, DateRange::COMPARE_BETWEEN, and DateRange::COMPARE_AFTER are set to -1, 0, and 1 (respectively).

Differences

Find the difference between the start and end dates:

$DateRange = new DateRange('Nov 4', 'Nov 8');
echo $DateRange->diff()->format('%d days); /// 4 days

Date range output

Convert date range to string and format date output:

$LaborDayWeekend = new DateRange('August 31, 2018', 'September 3, 2018');
echo $LaborDayWeekend->toString('m-d-Y'); /// 08-31-2018 - 09-03-2018
echo $LaborDayWeekend->toString('m-d-Y', 'Y-n-j'); /// 08-31-2018 - 2018-9-3
echo (string) $LaborDayWeekend; /// 2018-08-31 - 2018-09-03

Date range as array

Iterating over the $LaborDayWeekend date range defined in the previous example:

foreach ($LaborDayWeekend as $day) {
	echo $day->format('M j, Y');
	/// Aug 31, 2018
	/// Sep 1, 2018
	/// Sep 2, 2018
	/// Sep 3, 2018
}

Converting to an array of formatted date strings:

$week = new DateRange('Sunday', 'Saturday');
$days = $week->toArray('l');

/// $days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']

Excluding dates

The class constants DateRange::EXCLUDE_END_DATE and DateRange::EXCLUDE_START_DATE can be passed to the following methods to omit the start or end date from the results:

DateRange::getDatePeriod($interval, $exclude)
DateRange::compare($date, $exclude)
DateRange::toArray($format, $short, $interval, $exclude)

In a DateRange which spans from Sunday to Saturday, the EXCLUDE_* constants can be passed as the $exclude parameter, individually or together with a bitwise operator, to modify the range like so:

License

DateRange is licensed under the MIT license.

jasonjgardner / date-range

Maintainers

Details