date_timestamp_set()

Функция PHP date_timestamp_set()

date_timestamp_set() устанавливает дату и время объекта DateTime на основе Unix-метки времени — количества секунд, прошедших с 1 января 1970 года, 00:00:00 UTC («эпоха Unix»). Функция перезаписывает любую дату, которая была в объекте ранее, фиксируя его на точном моменте, описываемом меткой.

На этой странице рассматриваются синтаксис функции, рабочий пример, взаимодействие с часовыми поясами (то, в чём чаще всего ошибаются), объектно-ориентированный эквивалент DateTime::setTimestamp(), типичные сценарии использования, а также связь с другими функциями работы с датами в PHP.

Синтаксис

date_timestamp_set(DateTime $object, int $timestamp): DateTime

• $object — экземпляр DateTime, который требуется изменить.
• $timestamp — Unix-метка времени (секунды с начала эпохи). Для дат до 1970 года передайте отрицательное число.
• Возвращает — тот же объект DateTime (что позволяет объединять вызовы в цепочку), обновлённый до нового значения.

Поскольку функция изменяет переданный объект и возвращает его, date_timestamp_set() является процедурным аналогом метода DateTime::setTimestamp() — оба делают одно и то же.

Базовый пример

Следующий код устанавливает объект DateTime на 1 января 2022 года, 00:00:00 UTC, чья Unix-метка времени равна 1640995200:

Мы создаём объект DateTime, передаём его в date_timestamp_set() вместе с меткой времени, а затем форматируем результат с помощью format(). Исходная дата, которую установил конструктор (текущий момент), при этом отбрасывается.

Unix-метка времени всегда указывает на момент в UTC — она не несёт в себе информации о часовом поясе. Если вам нужна метка для конкретной календарной даты, используйте mktime(), strtotime() или (new DateTime('2022-01-01'))->getTimestamp().

Метки времени абсолютны — часовой пояс влияет только на отображение

Распространённое заблуждение состоит в том, что date_timestamp_set() «конвертирует» дату между часовыми поясами. Функция не меняет какой именно момент описывает объект; она лишь устанавливает этот момент. Часовой пояс влияет только на то, как format() отображает этот момент.

Одна и та же метка времени, отображённая в двух разных часовых поясах:

<?php
$timestamp = 1640995200; // 2022-01-01 00:00:00 UTC

$nyc = new DateTime('now', new DateTimeZone('America/New_York'));
date_timestamp_set($nyc, $timestamp);

echo $nyc->format('Y-m-d H:i:s P'); // 2021-12-31 19:00:00 -05:00

Момент времени идентичен, но Нью-Йорк в январе отстаёт от UTC на пять часов, поэтому показания местных часов соответствуют вечеру 31 декабря. Вызов $nyc->getTimestamp() по-прежнему вернёт 1640995200. Чтобы изменить отображаемый часовой пояс, задайте его явно с помощью date_timezone_set().

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

Если вы предпочитаете цепочки вызовов, DateTime::setTimestamp() работает идентично:

<?php
date_default_timezone_set('UTC');

$date = (new DateTime())->setTimestamp(1640995200);

echo $date->format('Y-m-d H:i:s'); // 2022-01-01 00:00:00

Оба стиля изменяют объект на месте и возвращают его, поэтому выбирайте тот, который лучше читается в вашем коде.

Типичные сценарии использования

• Восстановление сохранённого времени. Базы данных и API часто хранят время в виде целочисленных Unix-меток. date_timestamp_set() восстанавливает DateTime из такого целого числа, чтобы вы могли форматировать его или выполнять арифметические операции с помощью date_add() и date_diff().
• Нормализация пользовательского ввода. Преобразуйте введённую пользователем дату в метку с помощью strtotime(), а затем инициализируйте DateTime из этого единственного канонического значения.
• Сброс существующего объекта. Когда у вас уже есть настроенный DateTime (с выбранным часовым поясом или логикой форматирования) и вы хотите просто переключить его на новый момент, не пересоздавая заново.

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

• date_timestamp_get() — обратная операция: получение Unix-метки времени объекта DateTime.
• date_date_set() и date_time_set() — установка даты или времени по компонентам, а не по метке.
• date_default_timezone_set() — управление часовым поясом, используемым по умолчанию, когда DateTimeZone не задан.

Заключение

date_timestamp_set() устанавливает объект DateTime на точный момент, описываемый Unix-меткой времени, перезаписывая предыдущее значение и возвращая тот же объект. Помните, что метка времени всегда основана на UTC, а часовой пояс влияет только на отображение результата, но не на сам описываемый момент. Для обратной операции используйте date_timestamp_get().

Практика