Инициализирует новый экземпляр класса DatePeriod

Описание

public function DatePeriod::__construct(
    DateTimeInterface $start,
    DateInterval $interval,
    int $recurrences,
    int $options = 0
)

public function DatePeriod::__construct(
    DateTimeInterface $start,
    DateInterval $interval,
    DateTimeInterface $end,
    int $options = 0
)

Внимание

Устаревший конструктор:

public function DatePeriod::__construct(string $isostr, int $options = 0)

Начиная с PHP 8.4.0 вариант конструктора устарел; периоды на основе интервалов повторения в формате стандарта ISO 8601 создают методом DatePeriod::createFromISO8601String().

Метод инициализирует новый объект DatePeriod.

Объект DatePeriod работает как итератор для генерации серии объектов DateTimeImmutable или DateTime на основе трёх параметров: начальной даты start, интервала interval и дополнительно конечной даты end или количества повторений recurrences.

Объект периода генерирует объекты, класс которых эквивалентен классу объекта в параметре start: DateTimeImmutable или DateTime.

Список параметров

start

Начальная дата. По умолчанию включается в набор результатов.

interval

Интервал.

recurrences

Количество повторений: число больше 0. Объект периода выдаст на одно повторение больше, поскольку начальная дата по умолчанию включается в набор результатов.

end

Конечная дата. По умолчанию исключается из набора результатов.

isostr

Строка с интервалом повторения, формат которого описывает спецификация стандарта » ISO 8601. PHP поддерживает только часть спецификаций.

Пример отдельных спецификации интервалов по стандарту ISO 8601, которые PHP не поддерживает:

нулевое количество повторений: R0/
числовые обозначения смещения времени: +02:00; поддерживается только UTC-смещение Z

options

Битовое поле для управления границами периода.

DatePeriod::EXCLUDE_START_DATE: открывает границу слева и исключает начальную дату из набора повторений внутри периода.

DatePeriod::INCLUDE_END_DATE: закрывает границу справа и включает конечную дату в набор повторений внутри периода.

Ошибки

При передаче в параметр isostr интервала, формат которого не соответствует спецификациям стандарта ISO 8601, метод выбросит исключение DateMalformedPeriodStringException; до PHP 8.3 выбрасывалось исключение Exception.

Список изменений

Версия	Описание
8.4.0	Сигнатура с параметром `isostr` устарела; период на основе интервалов повторения в формате стандарта ISO 8601 создают методом DatePeriod::createFromISO8601String().
8.3.0	Вместо исключения Exception теперь выбрасывается исключение DateMalformedPeriodStringException.
8.2.0	Добавили константу `DatePeriod::INCLUDE_END_DATE`.
7.2.19, 7.3.6, 7.4.0	Параметр `recurrences` теперь принимает только значения больше `0`.

Примеры

Пример #1 Пример генерации последовательности дат через объект DatePeriod

<?php

$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');
$recurrences = 4;
$iso = 'R4/2012-07-01T00:00:00Z/P7D';

// Каждый следующий период создаст одинаковую последовательность дат
$period = new DatePeriod($start, $interval, $recurrences);
$period = new DatePeriod($start, $interval, $end);
$period = new DatePeriod($iso);

// При итерации по объекту DatePeriod повторяется генерация и вывод
// каждой даты внутри периода.
foreach ($period as $date) {
    echo $date->format('Y-m-d') . "\n";
}

Результат выполнения приведённого примера:

Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
2012-07-01
2012-07-08
2012-07-15
2012-07-22
2012-07-29

Пример #2 Пример исключения начальной даты из периода DatePeriod флагом DatePeriod::EXCLUDE_START_DATE

<?php

$start = new DateTime('2012-07-01');
$interval = new DateInterval('P7D');
$end = new DateTime('2012-07-31');

$period = new DatePeriod(
    $start,
    $interval,
    $end,
    DatePeriod::EXCLUDE_START_DATE
);

// При итерации по объекту DatePeriod повторяется генерация и вывод
// каждой даты внутри периода,
// кроме даты 2012-07-01.
foreach ($period as $date) {
    echo $date->format('Y-m-d') . "\n";
}

Результат выполнения приведённого примера:

Пример #3 Пример вывода через объект DatePeriod даты последнего четверга для каждого месяца года

<?php

$begin = new DateTime('2021-12-31');
$end = new DateTime('2022-12-31 23:59:59');

$interval = DateInterval::createFromDateString('last thursday of next month');
$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

foreach ($period as $dt) {
    echo $dt->format('l Y-m-d'), "\n";
}

Результат выполнения приведённого примера:

Thursday 2022-01-27
Thursday 2022-02-24
Thursday 2022-03-31
Thursday 2022-04-28
Thursday 2022-05-26
Thursday 2022-06-30
Thursday 2022-07-28
Thursday 2022-08-25
Thursday 2022-09-29
Thursday 2022-10-27
Thursday 2022-11-24
Thursday 2022-12-29

Примечания

Неограниченное количество повторений не поддерживается, поэтому ни передача спецификатора "R/..." в параметр isostr, ни передача null в параметр end — не сработает. Подробнее о повторных интервалах времени рассказывает раздел 4.5 "Recurring time interval" стандарта ISO 8601.