Date Intervals and Periods

Date intervals and date periods are objects used to represent specific spans of time and sequences of dates.

A date interval represents a time span. It's an instance of the DateInterval class, and you can use it to add or subtract specific periods, like days, months, years, hours, etc., from a DateTime object.

A date period represents a sequence of specific dates, iterating over a period using a start date, an interval, and an end date or recurrences. It's implemented as the DatePeriod class.

Both DateInterval and DatePeriod objects offer flexibility and ease in manipulating and working with dates, whether you want to represent a specific time span or iterate through a sequence of dates. They integrate well with the DateTime class, making date calculations and manipulations more intuitive in PHP.

Let's look at both classes.

Date Intervals

The DateInterval class in PHP is used to represent a span of time. It allows you to define a specific interval, such as a number of days, weeks, months, years, hours, minutes, or seconds, and it can be both positive and negative.

It helps in performing date arithmetic, understanding differences between dates, formatting intervals, and setting up recurring events. It integrates seamlessly with the DateTime class and other date-related functions, making it an essential tool for date manipulation and calculations.

You can create a DateInterval object by providing an interval specification string to its constructor. An interval specification is a string used to define a time period in the DateInterval class. It is constructed using specific letters to represent different components of the interval, like years, months, days, hours, minutes, and seconds.

Here are some examples of various interval specifications:

When using the interval specification, you begin with the letter P, followed by the time parts using the appropriate letters: Y for years, M for months, D for days, H for hours, M for minutes, and S for seconds. If you include time components (hours, minutes, seconds), you must precede them with the letter T.

Let's look at an example of creating an instance of this class.

$interval = new DateInterval('P2Y4M6DT10H'); // 2 years, 4 months, 6 days, and 10 hours

Adding and Subtracting from a Date

You can use this instance to help you add or subtract from a DateTime object, effectively changing the date and time. The DateTime class has two methods called add() and sub() for adding and subtracting from the current date, respectively. Both methods accept an instance of the DateInterval class.

$date = new DateTime();
$date->add($interval); // Adds the interval
$date->sub($interval); // Subtracts the interval

Difference Between Dates

You can use DateInterval to represent the duration between two dates, such as the difference in age, time elapsed between events, etc. The DateTime class has a method called diff() for finding the difference between two dates. It'll return an instance of the DateInterval class.

$date1 = new DateTime('2023-01-01');
$date2 = new DateTime('2023-12-31');
$interval = $date1->diff($date2); // Calculates the difference

Formatting the Date Interval

You may want to display the interval. In that case, you can use the format() method. The format() method of the DateInterval class is used to format the interval as a string according to a specific format. This method allows you to present the interval information in a customized way that's suitable for your application.

A string format can be passed in that the resulting string must adhere to. It can include various placeholders that represent different parts of the interval, prefixed with a percentage symbol (%).

Here's a list of used format placeholders:

• %y: Years
• %m: Months
• %d: Days
• %h: Hours
• %i: Minutes
• %s: Seconds
• %%: A literal percentage sign

Here's an example of how you can use the format method:

$interval = new DateInterval('P2Y3M4DT5H6M7S');
 
echo $interval->format('%y years %m months %d days %h hours %i minutes %s seconds');
// Output: 2 years 3 months 4 days 5 hours 6 minutes 7 seconds

You can also include literals and other characters to enhance the output:

echo $interval->format('%y years, %m months, and %d days (Total: %a days)');
// Output: 2 years, 3 months, and 4 days (Total: 833 days)

The %a format returns the total number of days as a result of the interval.

Some formats may return 0 if that part of the interval is not set.

Date Periods

The DatePeriod class in PHP is used to handle a period of time, representing a sequence of specific dates and times that recur according to a defined interval. It's particularly handy for iterating through dates and is often used in scenarios where recurring events are needed.

Overall, it provides an intuitive and efficient way to represent and work with recurring dates in PHP. By defining a start date, an interval, and an end date or the number of recurrences, you can iterate over a sequence of dates, making it an ideal solution for working with patterns of dates.

You can create a DatePeriod object by providing the following parameters to its constructor:

• Start Date: A DateTime object representing the start of the period.
• Interval: A DateInterval object representing the interval between occurrences within the period.
• End Date/Recurrences: Either a DateTime object representing the end date of the period or an integer specifying the number of recurrences.

Here's a basic example:

$start = new DateTime('2023-01-01');
$interval = new DateInterval('P1D'); // 1 day
$period = new DatePeriod($start, $interval, 5); // 5 days
 
foreach ($period as $date) {
  echo $date->format('Y-m-d'), "\n";
}

The code snippet provided will create a DatePeriod instance that starts on January 1, 2023, and iterates over a period of 5 days, with a 1-day interval between each date. The output will be:

2023-01-01
2023-01-02
2023-01-03
2023-01-04
2023-01-05
2023-01-06

The DatePeriod class is an iterator, so you can loop through it using a foreach loop to process each date in the sequence. In the example above, after creating an instance of the DatePeriod class, we're looping through the object. As we do so, we'll have access to an instance of the DateTime class. Therefore, we can use the format() method to display a human-readable date.

Key Takeaways

• DateInterval represents a span of time, defined in terms like years, months, days, hours, minutes, and seconds.
• Can be added or subtracted to/from DateTime objects.
• Can be formatted to a string with the format method, using placeholders like %y, %m, etc.
• The %a format can give the total days of the interval.
• DatePeriod represents a sequence of dates that recur according to a specific interval.
• Created using a start DateTime, an interval DateInterval, and either an end date DateTime or a number of recurrences.