Download the PHP package madison-solutions/just-date without Composer

php-just-date

PHP library for dealing with dates without any time information, and times without any date information

There are several excellent PHP libraries for working with DateTime objects. But sometimes you need to deal with only the date part, or only the time part of a DateTime object.

For example, a hotel booking system might care only about a guest's check-in date - and the exact time of arrival is unimportant. In those situations, all of the functionality relevant to the time of day just gets in the way, making things like comparisons and equality checks awkward. Added complications like timezones and daylight saving time further muddy the waters.

This library aims to make it simple to work with just the date part, or just the time part.

See below for a quick guide to the functionality, with some examples, or see the API reference here.

Note these instructions are for version 2 - see the migration guide for help migrating from version 1.

Install

JustDate

Represents a single date with no time information

Basic Use

Time is ignored

Today's date

Traversing the calendar

Note JustDate objects are immutable - nextDay() and all other similar methods return new instances of JustDate!

Working days

DateRange

Represents a range of dates between some start date and some end date (with no time information).

Note you can't create a range where $start is after $end

If you're not sure which of your 2 dates comes first, you can use eitherWayRound().

Intersection of 2 ranges

Iterating over a range

Length of a DateRange

Whenever you talk about the 'length' of a date range, there's an ambiguity about what this means.

For example, if you have a DateRange where $start is Tuesday 4th, and $end is Monday 8th, as per the diagram below, then what should the 'length' of the range be?

There are 2 fairly reasonable, but different definitions.

You could count the number of days that are included in the range (inclusive of start and end dates). In the example above the answer would be 5. This could also be thought of as the length in days, measured from the first second of the start date to the last second of the end date. By this definition, the smallest possible DateRange, where start and end are the same day, would have length 1.

Alternatively you could define the length by subtracting the start date from the end date. In the example above, the answer would be 8 - 4 = 4. This could also be thought of as the length in days, measured from the middle of the start date to the middle of the end date, or as the number of nights that occur between the start and end date. By this definition, the smallest possible DateRange, where start and end are the same day, would have length 0.

The DateRange class provides both options - the first is accessed as $range->outer_length and the second is accessed as $range->inner_length.

JustTime

Represents a time without any date information.

Date info is ignored

The date part is removed, as well as the timezone. If date parameters are used in a format string, the date will be 1 Jan 1970 (unix epoch).

The time now

Traversing the clock

Note JustTime objects are immutable - addTime() returns new instances of JustTime!

Rounding to a certain interval

DateSet and MutableDateSet

Represent a set of dates (not necessarily a continuous range). MutableDateSet can have dates added or removed, DateSet cannot be changed after it is created.

Combining / Comparing DateSets

The contains($other) method of DateSet and MutableDateSet can be used to compare with other objects to test whether they contain all of the dates in the other object. The other object does not have to be the same type, it can be a JustDate, DateRange, DateSet or MutableDateSet (or anything else implementing the DateRangeList interface).

The isSameAs($other) method of DateSet and MutableDateSet can be used to compare with other objects to test whether they contain the exact same set of dates. Again the other object does not have to be the same type.

Iterating over a DateSet

You can choose to iterate over the continuous ranges in the set, or over the individual dates.