DateTime в Битрикс D7: работа с датами и форматами

Bitrix\Main\Type\DateTime — обёртка над стандартным PHP DateTime, обязательная к использованию при работе с датами через D7 API. Разберём, зачем она вообще нужна, если в PHP уже есть свой класс дат, и какие ошибки чаще всего возникают при смешивании форматов.

Почему нельзя просто передать обычный DateTime

<?php

use Bitrix\Main\UserTable;
use Bitrix\Main\Type\DateTime;

UserTable::update($userId, [
    'LAST_LOGIN' => new DateTime(), // именно Bitrix\Main\Type\DateTime
]);

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

Создание из строки

<?php

use Bitrix\Main\Type\DateTime;

$date = new DateTime('15.03.2026', 'd.m.Y');
$date = DateTime::createFromTimestamp(time());

Формат даты в конструкторе привязан к настройкам сайта (d.m.Y для русской локали по умолчанию) — при разборе строки в ином формате (например, ISO 8601 из внешнего API) формат нужно указать явно вторым параметром, иначе разбор либо завершится ошибкой, либо даст неожиданную дату.

Нужна помощь с Битрикс?

Разбор даты из внешнего API (ISO 8601)

<?php

use Bitrix\Main\Type\DateTime;

$isoString = '2026-03-15T14:30:00+03:00';

$date = DateTime::createFromUserTime($isoString, 'Y-m-d\TH:i:sP');

Сравнение и арифметика с датами

<?php

use Bitrix\Main\Type\DateTime;

$now = new DateTime();
$deadline = new DateTime('20.03.2026', 'd.m.Y');

if ($now->getTimestamp() > $deadline->getTimestamp()) {
    echo 'Срок истёк';
}

$nextWeek = (clone $now)->add('7 days');

Метод add() изменяет объект и возвращает его же — для вычисления новой даты без изменения исходного объекта необходимо явно клонировать через clone, иначе исходная переменная тоже сдвинется на новое значение, что часто оказывается неожиданным побочным эффектом.

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

<?php

echo $date->format('d.m.Y H:i');
echo $date->toString(); // формат по настройкам сайта

toString() форматирует дату по правилам текущего сайта (формат из настроек, при необходимости — с учётом языка), а format() принимает явный PHP-формат, как у стандартного класса. Для показа даты пользователю в интерфейсе сайта обычно предпочтителен toString(), чтобы формат оставался консистентным с остальными датами на сайте.

Часовые пояса

При работе с датами, полученными от внешних систем в другом часовом поясе, важно явно проверять и, если нужно, приводить их к часовому поясу сайта перед сохранением — иначе время в базе может отличаться от ожидаемого на количество часов смещения между поясами, что особенно заметно на записях, близких к полуночи.

Частые ошибки

Передан стандартный \DateTime вместо Bitrix\Main\Type\DateTime. ORM-метод не принимает значение или падает с ошибкой типа.
Формат строки не совпадает с ожидаемым при разборе. Дата разбирается неверно или выбрасывает исключение.
add() без clone меняет исходный объект. Неожиданное изменение переменной, которая использовалась в нескольких местах кода.
Не учтён часовой пояс данных из внешнего источника. Сохранённое время смещено на количество часов разницы поясов.

Итог

Bitrix\Main\Type\DateTime обязателен для всех D7 API-методов, работающих с датами, — стандартный PHP DateTime здесь не подходит. При разборе строк из внешних источников формат нужно указывать явно, а при арифметике с датами — помнить, что add() изменяет сам объект и требует clone для сохранения исходного значения.

Теги: D7 Разработка