PHP функция date_time_set()

В PHP метод DateTime::setTime() используется для установки нового времени для заданного объекта DateTime. Этот метод является частью класса PHP DateTime и позволяет задать временну́ю часть объекта даты/времени новым значением.

Синтаксис

Синтаксис метода DateTime::setTime() выглядит следующим образом:

Синтаксис метода DateTime::setTime()

$datetime->setTime($hour, $minute, $second, $microsecond);

Где:

• $datetime — объект DateTime, который нужно изменить.
• $hour — новое значение часа (0–23).
• $minute — новое значение минут (0–59).
• $second — новое значение секунд (0–59, необязательный, по умолчанию 0).
• $microsecond — новое значение микросекунд (0–999999, необязательный, по умолчанию 0).

Примечание: часовой пояс объекта DateTime сохраняется в ходе операции. Метод изменяет объект на месте. Если переданные значения выходят за пределы допустимых диапазонов, PHP автоматически нормализует их (например, час 25 переходит на следующий день), не выбрасывая исключения.

Пример использования

Рассмотрим пример использования метода DateTime::setTime():

Пример метода PHP DateTime::setTime()

В этом примере мы сначала создаём новый объект DateTime с датой и временем '2000-01-01 12:00:00'. Затем используем метод setTime(), чтобы установить час 14 и минуты 30. Наконец, метод format() выводит изменённые дату и время в формате 'Y-m-d H:i:s'. Результат:

2000-01-01 14:30:00

Так как мы не передали $second и $microsecond, оба параметра принимают значение 0, поэтому секунды сбрасываются, даже если в исходном времени они уже были :00.

Установка секунд и микросекунд

Можно передать все четыре аргумента, чтобы управлять временем вплоть до микросекунд. Компонент микросекунд отображается в выводе только если строка формата содержит u:

<?php
$date = new DateTime('2000-01-01 12:00:00');
$date->setTime(14, 30, 15, 500000);
echo $date->format('Y-m-d H:i:s.u');

Выводит 2000-01-01 14:30:15.500000.

Значения вне диапазона переносятся

setTime() не выбрасывает исключение при значениях вне допустимого диапазона — он нормализует их, перенося переполнение в дату. Установка часа в 25 сдвигает дату вперёд на один день:

<?php
$date = new DateTime('2000-01-01 23:30:00');
$date->setTime(25, 0);
echo $date->format('Y-m-d H:i:s');

Выводит 2000-01-02 01:00:00 — час 25 становится 01:00 следующего дня. Это удобно для арифметики (например, «добавить 5 часов», передав $hour + 5), но может стать источником скрытых ошибок, если ожидалась валидация. Чтобы изменить дату напрямую, используйте setDate() или modify() для относительных сдвигов.

Сравнение DateTime::setTime() с другими функциями

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

Это отличает его от DateTimeImmutable::setTime(), который возвращает новый экземпляр и не затрагивает оригинал:

<?php
$original = new DateTimeImmutable('2000-01-01 12:00:00');
$changed  = $original->setTime(8, 0);

echo $original->format('H:i'), ' | ', $changed->format('H:i');

Выводит 12:00 | 08:00: $original остаётся неизменным, а $changed содержит новое время. При использовании изменяемого DateTime вызов возвращает тот же объект, который был изменён, поэтому $original и $changed указывали бы на один объект со временем 08:00. Предпочитайте DateTimeImmutable, когда значение используется совместно или передаётся в несколько мест, чтобы избежать случайных изменений.

Связанные методы, которые могут понадобиться вместе с setTime(): setDate() для изменения года/месяца/дня, setTimezone() для перевода в другой часовой пояс и date_default_timezone_set() для установки часового пояса по умолчанию для всего скрипта. Чтобы создать объект, смотрите new DateTime.

Заключение

Метод DateTime::setTime() — полезный инструмент для работы с датами и временем в PHP. Предоставляя простой способ обновления временно́й части объекта DateTime, он предлагает удобный и надёжный подход к манипуляциям с датой/временем. Для работы с неизменяемыми датами используйте DateTimeImmutable::setTime(), который возвращает новый экземпляр вместо изменения оригинала.

Практика