Bitrix «1С-Битрикс»: D7-класс Type\DateTime — создание, вывод и add()

Почему отдельный класс

В коде административного ядра D7 значения календаря чаще всего приходят как экземпляр Bitrix\Main\Type\DateTime. Обычно перед работой добавляют use Bitrix\Main\Type\DateTime;. Он напоминает встроенный \DateTime по возможностям, но не является его наследником: у Bitrix свой слой локализации, учёт региональных форматов из настроек портала и единое поведение при сериализации в ORM и отчётных выборках.

Откуда взять объект

Есть два «фабричных» входа без ручного разбора строки: из готового PHP-объекта и из метки времени. Конструкторы покрывают повседневные случаи — «прямо сейчас», парсинг в формате, принятом на сайте как FORMAT_DATETIME, или явное указание шаблона разбора.

use Bitrix\Main\Type\DateTime;

$webinarStarts = DateTime::createFromPhp(
    new \DateTime('2026-04-09 17:45:00', new \DateTimeZone('Europe/Moscow'))
);

$issuedAt = DateTime::createFromTimestamp(1724080800);

$instant = new DateTime();
$shortLocal = new DateTime('03.06.2026 09:30');
$preciseDb = new DateTime('2026-11-11 08:05:42', 'Y-m-d H:i:s');

Строки и UNIX-время

Для API и логирования нужны разные текстовые формы: целое число секунд, человекочитаемая строка в проектном формате и произвольный шаблон — последний просто пробрасывается во встроенный DateTimeInterface::format.

$slot = DateTime::createFromPhp(new \DateTime('2026-08-01 00:00:00'));

$unix = $slot->getTimestamp();
$forGrid = $slot->toString();
$isoMinute = $slot->format('c');

Смещение дат: метод add()

Метод add() изменяет сам объект, поэтому при серии экспериментов удобно заранее сделать clone. Строкой можно описать сдвиг словами years/months/days/weeks/hours/minutes/seconds и знаками +/-, комбинируя фрагменты вроде «два месяца минус одна неделя плюс пятнадцать минут».

Форматы DateInterval тоже поддерживаются: префикс P необязателен, главное — записывать блоки сверху вниз по крупности (год → месяц → день → время), иначе разбор становится двусмысленным.

$anchor = new DateTime('01.07.2026 08:15:00');

$grace = clone $anchor;
$grace->add('+20 days');

$billing = clone $anchor;
$billing->add('3 months - 1 week + 2 hours');

$arrearsNotice = clone $anchor;
$arrearsNotice->add('P45DT6H30M');
$arrearsNotice->add('-P1YT10M');

Практические советы

• Если в одном методе смешиваете legacy на ConvertDateTime и D7, приводите оба конца к Type\DateTime, чтобы не ловить ошибки типов при ->getList().
• Для сравнения «что позже» вызывайте getTimestamp() или переводите в PHP-\DateTime только там, где нужны зоны времени извне конфигурации портала.
• После нескольких add() в цикле убедитесь, что изменяете копию, а не переданную из ORM ссылку на одно поле строки результата.

Краткий итог

Bitrix\Main\Type\DateTime закрывает рутину парсинга и преобразований между форматами сайта, PHP и базой данных. Освоив три входа создания (new, createFromPhp, createFromTimestamp), вывод в строку или число и дисциплину работы с add(), можно уверенно писать бизнес-логику вокруг SLA, подписок и отчётов без самодельных обёрток.