Сдвинуть дату на интервал Date::add

Модуль: main — подключать отдельно не нужно

Доступно с версии: 14.0.18

Метод Date::add сдвигает дату на интервал и возвращает тот же объект. Метод меняет текущий объект. Чтобы сохранить исходную дату, сдвигайте копию, полученную оператором clone.

Аналог в классическом API — функция AddToTimeStamp.

Сигнатура метода в классе Bitrix\Main\Type\Date:

public function add($interval)

Параметры

Обязательные параметры обозначены *

Параметр Тип Описание
interval* string Задает интервал в формате ISO 8601 или относительный период, например '+5 days'

Тип в таблице описывает назначение аргумента. Сигнатура PHP не объявляет его.

Форматы интервала

Метод принимает интервал в одном из двух форматов.

Интервал ISO 8601 без пробелов. Строка состоит из чисел и букв периода. Буква Y обозначает годы, M — месяцы, W — недели, D — дни. Часы H, минуты M и секунды S пишите после буквы T. Например, 2D — два дня, T2S — две секунды, 6YT5M — шесть лет и пять минут. Буква P в начале необязательна, регистр букв не важен. Знак - в начале задает сдвиг назад, например -P1M.

Относительный период. Строка с пробелами, которую разбирает метод PHP DateInterval::createFromDateString, например '+5 days', '-7 weekdays', '3 months - 5 days'.

Строку без пробелов метод сначала разбирает как интервал ISO 8601. Если не получилось, метод передает ее в DateInterval::createFromDateString.

Возвращаемое значение

Метод возвращает текущий объект, поэтому вызовы можно объединять в цепочку.

Особенности

  • Буква M без T означает месяцы. Чтобы сдвинуть на минуты, пишите T30M.
  • Сдвиг на месяц переносит несуществующий день на следующий месяц. Например, 31 января после 1M становится 3 марта.
  • Интервал с часами или минутами меняет и время объекта Date. Например, после T2H объект хранит время 02:00.
  • Если PHP не разобрал строку, метод оставляет дату без изменений. Это поведение проверено на PHP 8.2.

Примеры

Пример. Код сдвигает дату интервалами ISO 8601 на десять дней вперед и на месяц назад:

<?php
use Bitrix\Main\Type\Date;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$date = new Date('2026-01-15', 'Y-m-d');
$date->add('10D');
echo $date->format('Y-m-d') . ' ';

$date->add('-P1M');
echo $date->format('Y-m-d');

Код выведет 2026-01-25 2025-12-25.

Пример. Код получает дату через три рабочих дня и не меняет исходную дату:

<?php
use Bitrix\Main\Type\Date;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$start = new Date('2026-01-16', 'Y-m-d');
$deadline = (clone $start)->add('+3 weekdays');

echo $start->format('Y-m-d') . ' ' . $deadline->format('Y-m-d');

Код выведет 2026-01-16 2026-01-21. Период weekdays не учитывает субботу и воскресенье.

Смотрите также