date_isodate_set()

Функция date_isodate_set() устанавливает дату объекта DateTime с использованием недельного календаря ISO 8601 — то есть по году, номеру недели и дню недели, а не по месяцу и числу. Это процедурный псевдоним метода DateTime::setISODate(), поэтому оба делают одно и то же.

На этой странице описан синтаксис функции, отличие недельного календаря ISO от обычного, запускаемые примеры и типичные подводные камни.

Синтаксис

Функция date_isodate_set() имеет следующий синтаксис:

Синтаксис PHP функции date_isodate_set()

date_isodate_set(DateTime $object, int $year, int $week, int $dayOfWeek = 1): DateTime

где:

• $object — объект DateTime, который нужно изменить (изменяется непосредственно).
• $year — год по ISO.
• $week — номер ISO-недели, от 1 до 53.
• $dayOfWeek — день недели: 1 для понедельника, 7 для воскресенья (необязательный, по умолчанию 1).

Функция возвращает тот же объект DateTime, поэтому вызовы можно объединять в цепочку. Эквивалентный объектно-ориентированный вызов:

$date->setISODate($year, $week, $dayOfWeek);

Зачем использовать даты ISO-недели

В отличие от обычного календаря, ISO 8601 нумерует каждую неделю года и идентифицирует дату по (год, неделя, день недели). Это удобно для бизнес-отчётности, планирования и любых систем, работающих с неделями, а не с месяцами.

Стоит запомнить два правила:

• Неделя 1 — это неделя, содержащая первый четверг года — или, что равнозначно, неделя, содержащая 4 января. Из-за этого первые дни января могут принадлежать предыдущему ISO-году, а последние дни декабря — следующему.
• Значения за пределами диапазона переполняются, а не вызывают ошибку. Запрос недели 53 или дня 7 для несуществующей недели просто сдвигает дату вперёд на следующую неделю или год. Например, date_isodate_set($d, 2022, 52, 7) приводит к 2023-01-01, потому что 52-я неделя 2022 года заканчивается в воскресенье, 1 января 2023 года.

Примечание: date_isodate_set() изменяет только дату. Время суток остаётся таким, каким оно уже было у объекта DateTime (текущее время для только что созданного объекта).

Примеры

Базовое использование

Устанавливаем дату на 3-й день (среду) 10-й ISO-недели 2023 года:

Функция изменяет $date непосредственно. Мы начинаем с фиксированного времени, чтобы вывод был одинаковым при каждом запуске; заменяется только часть с датой.

Номера недель могут пересекать границу года

Запрос последнего дня последней недели 2022 года приводит к январю 2023 года — это особенность календаря ISO, а не ошибка:

52-я неделя 2022 года заканчивается в воскресенье, 1 января 2023 года — именно эта дата и возвращается.

Объектно-ориентированный эквивалент

DateTime::setISODate() выполняет ту же задачу и возвращает объект, что позволяет сразу вызвать format() в цепочке:

Это устанавливает дату на 1-й день (понедельник) 24-й недели 2023 года.

Связанные функции

• date_create() — создать объект DateTime для передачи в функцию.
• date_format() — форматировать полученную дату для вывода.

Заключение

date_isodate_set() устанавливает DateTime на конкретную точку (год, неделя, день недели) с использованием недельного календаря ISO 8601. Помните, что ISO-неделя 1 содержит первый четверг года, что значения недели и дня при выходе за пределы диапазона переходят к следующей неделе или году без ошибки, и что изменяется только дата, но не время.

Практика