Работа с датами и временем в современных веб-приложениях — одна из ключевых задач. В платформе 1С-Битрикс существует собственный класс для удобного и безопасного манипулирования датами и временем — это класс DateTime. Он расширяет функциональность класса Date и значительно упрощает такие операции, как форматирование, парсинг, сравнение дат, операции с часовыми поясами и т. д.
В данной статье рассмотрим основные возможности DateTime на примерах, а также общие принципы работы с ним в рамках D7.
1. Общая информация о классе DateTime
1.1. Наследование от Date
Класс DateTime унаследован от Date. Это значит, что он поддерживает весь функционал класса Date, но предоставляет дополнительную возможность учитывать и время (часы, минуты, секунды). В результате в большинстве мест ядра 1С-Битрикс при работе с датами/временем используется именно DateTime.
1.2. Пространство имён
Библиотеки D7 в 1С-Битрикс используют неймспейсы. Чтобы работать с классом DateTime, необходимо указывать его полное пространство имён:
use Bitrix\Main\Type\DateTime;Либо сразу обращаться к нему через:
\Bitrix\Main\Type\DateTime2. Создание объекта DateTime
2.1. Конструктор
Самый очевидный способ создать объект класса DateTime — вызвать его конструктор. В конструктор можно передать строку с датой и временем в удобном вам формате, а также (необязательно) строку с форматом для парсинга.
Пример:
use Bitrix\Main\Type\DateTime;
// Пример 1. Создание объекта с текущими датой и временем
$currentDateTime = new DateTime(); // Если не передавать параметры, по умолчанию возьмется текущее время
// Пример 2. Создание объекта с указанием конкретной даты/времени
$dateString = '2025-03-10 15:30:00';
$dateFormat = 'Y-m-d H:i:s';
$customDateTime = new DateTime($dateString, $dateFormat);
// Пример 3. Создание объекта из даты без указания времени
// Система поставит время 00:00:00
$dateOnly = new DateTime('2025-03-10', 'Y-m-d');2.2. Использование объекта Date при создании
Если у вас уже есть объект типа Date и вы хотите дополнить его информацией о времени, то при создании DateTime можно передать ему строку с временем отдельным параметром или внести изменения в сам объект Date методами класса. Однако в большинстве случаев, когда нужно управлять временем, изначально используют DateTime.
3. Форматирование и вывод дат
Форматирование даты и времени в D7 осуществляется стандартными механизмами PHP или методами, унаследованными классом DateTime. Например, для вывода даты в нужном формате чаще всего используют метод format().
use Bitrix\Main\Type\DateTime;
$dateTime = new DateTime();
echo $dateTime->format('d.m.Y H:i:s');
// Выведет что-то вроде: 12.03.2025 14:45:00Метод format() принимает строку формата, в которой используются стандартные символы форматирования времени и даты в PHP (d, m, Y, H, i, s и т. д.).
4. Важные методы и операции
Ниже рассмотрим несколько ключевых возможностей DateTime, которые пригодятся в большинстве сценариев.
4.1. Получение Unix-времени (timestamp)
Иногда требуется получить «сырое» время в виде количества секунд с 1 января 1970 года (UTC). С помощью getTimestamp() можно получить это значение:
$timestamp = $dateTime->getTimestamp();
echo $timestamp;
// Например, 17423403004.2. Конвертация в различное локальное представление
При работе в разных часовых поясах или при локализации проекта под разные языки и региональные настройки — правильное отображение времени может оказаться нетривиальной задачей.
В Битрикс D7 предусмотрен метод toString() для получения строки в стандартном формате, принятом в Битрикс (обычно это YYYY-MM-DD HH:MI:SS), а также методы, позволяющие получать дату/время в том или ином виде.
Однако в большинстве случаев разработчики пользуются format(), чтобы явно указать желаемый вид строки.
4.3. Сравнение дат
Частая задача — сравнить две даты. Например, нужно понять, наступило ли определенное время, либо сколько дней между двумя датами. Объекты DateTime легко сравниваются через стандартные операторы PHP:
$dateTime1 = new DateTime('2025-03-10 10:00:00', 'Y-m-d H:i:s');
$dateTime2 = new DateTime('2025-03-10 12:00:00', 'Y-m-d H:i:s');
if ($dateTime1 < $dateTime2) {
echo 'dateTime1 раньше dateTime2';
} else {
echo 'dateTime1 позже или равно dateTime2';
}Также можно вычислять разницу между датами методами, унаследованными от базовых PHP-классов (diff()) и при необходимости переводить результат в дни, часы и т. д.
5. Работа с часовыми поясами
5.1. Часовой пояс по умолчанию
Битрикс по умолчанию использует системный часовой пояс, который задан в настройках проекта. При создании объекта DateTime он автоматически будет учитывать конфигурацию часового пояса приложения (если вы не укажете что-то иное).
5.2. Установка другого часового пояса
Если требуется вручную задать часовой пояс для конкретной даты, можно воспользоваться стандартными средствами PHP (например, передав объект типа DateTimeZone):
use Bitrix\Main\Type\DateTime;
$tz = new \DateTimeZone('Europe/London');
$dateTimeLondon = new DateTime('2025-03-10 15:30:00', 'Y-m-d H:i:s', $tz);
echo $dateTimeLondon->format('Y-m-d H:i:sP');В данном случае время будет интерпретироваться исходя из временной зоны Europe/London.
6. Основные примеры использования
Ниже приведено несколько распространённых сценариев, с которыми вы можете столкнуться при разработке под 1С-Битрикс.
6.1. Подстановка текущей даты/времени в поле ORM
При работе с ORM в D7, когда вам нужно записать в базу данных текущее время, достаточно создать объект DateTime без параметров:
use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\Type\DateTime;
class DemoTable extends DataManager
{
public static function getTableName()
{
return 'demo_table';
}
public static function getMap()
{
return [
'ID' => [
'data_type' => 'integer',
'primary' => true,
'autocomplete' => true
],
'CREATED_AT' => [
'data_type' => 'datetime',
'required' => true
],
// ... остальные поля
];
}
}
// При добавлении новой записи:
$result = DemoTable::add([
'CREATED_AT' => new DateTime() // текущая дата и время
]);
if ($result->isSuccess()) {
echo "Запись успешно добавлена!";
} else {
echo "Произошла ошибка при добавлении записи!";
}6.2. Фильтрация записей по дате
Чтобы выбрать записи за определённый день или временной промежуток, мы используем возможности ORM и DateTime.
$startDate = new DateTime('2025-03-10 00:00:00', 'Y-m-d H:i:s');
$endDate = new DateTime('2025-03-10 23:59:59', 'Y-m-d H:i:s');
$rows = DemoTable::getList([
'filter' => [
'>=CREATED_AT' => $startDate,
'<=CREATED_AT' => $endDate,
],
])->fetchAll();
foreach ($rows as $row) {
echo $row['ID'] . ' — ' . $row['CREATED_AT']->format('d.m.Y H:i:s') . '
';
}Такой код выберет все записи, созданные 10 марта 2025 года.
6.3. Операции над датами: добавление/вычитание интервала
При работе с объектами DateTime можно выполнять операции над датами — добавлять или вычитать дни, часы, минуты. Используется для этого стандартный интерфейс класса DateInterval (из PHP) и метод add() или sub().
$dateTime = new DateTime('2025-03-10 10:00:00', 'Y-m-d H:i:s');
// Добавим 2 дня
$dateTime->add(new \DateInterval('P2D'));
echo $dateTime->format('Y-m-d H:i:s');
// Итоговая дата будет 2025-03-12 10:00:00
// Вычтем 3 часа
$dateTime->sub(new \DateInterval('PT3H'));
echo $dateTime->format('Y-m-d H:i:s');
// Итоговая дата станет 2025-03-12 07:00:007. Рекомендации по работе с датами в Битрикс
- Используйте объекты
DateTime. Избегайте хранения дат в виде обычных строк — это может приводить к некорректной работе при смене часового пояса, а также затрудняет форматирование и сравнение. - Всегда указывайте формат при создании объекта из строки. Так вы явно даёте понять, как нужно парсить входные данные.
- Отдельно учитывайте часы, если они важны. Если во всех сценариях важно только число и месяц (например, это день рождения без точной информации о времени), можно использовать класс
Date. Если же сценарии подразумевают часы и минуты, лучше сразу использоватьDateTime. - Будьте аккуратны с часовыми поясами. В разных окружениях (DEV, PROD) могут стоять разные временные зоны, а пользовательский интерфейс может требовать отображать локальное время клиента. В сложных случаях придётся использовать методы или настройки, которые учитывают часовой пояс пользователя.
Заключение
Класс DateTime в D7 — мощный инструмент для работы с датами и временем в 1С-Битрикс. Он предлагает удобный и унифицированный способ манипулировать временем, учитывая при этом нюансы PHP и особенности ядра Bitrix. Благодаря поддержке стандартных методов PHP (format(), diff(), add(), sub() и т. д.), вы можете гибко оперировать датами и обеспечивать корректность данных независимо от часового пояса и других факторов.
Используйте DateTime всякий раз, когда вам нужно работать с датами в Битрикс, и вы упростите себе жизнь, сделав код более чистым, читабельным и надёжным.