date_timestamp_get()

Введение

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

Понимание date_timestamp_get()

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

Метка времени всегда основана на UTC. Часовой пояс входного объекта DateTime используется для вычисления значения, однако сама метка не хранит часовой пояс — два объекта DateTime, описывающих один и тот же момент в разных часовых поясах, вернут одинаковую метку.

Синтаксис

date_timestamp_get(DateTimeInterface $object): int

• $object — экземпляр DateTime или DateTimeImmutable (любой объект, реализующий DateTimeInterface). Передача null или не-object вызывает TypeError в PHP 8+.
• Возвращаемое значение — int, Unix-метка времени в секундах. (Микросекунды отбрасываются; используйте $date->format('U.u'), если они нужны.)

Объект DateTime можно создать с помощью функции date_create() или конструктора класса DateTime. date_timestamp_get($date) является процедурным псевдонимом вызова метода $date->getTimestamp().

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

Мы создаём объект DateTime из строки с датой, передаём его в date_timestamp_get() и выводим возвращённую Unix-метку времени. Для современного объектно-ориентированного кода эквивалентная (и обычно предпочтительная) форма — $date->getTimestamp().

Влияние часового пояса на результат

Поскольку метка времени — это абсолютный момент в UTC, одна и та же строка с временем даёт разные метки в зависимости от часового пояса объекта:

<?php
$utc = new DateTime('2023-03-03 10:30:00', new DateTimeZone('UTC'));
$tokyo = new DateTime('2023-03-03 10:30:00', new DateTimeZone('Asia/Tokyo'));

echo date_timestamp_get($utc);   // 1677839400
echo "\n";
echo date_timestamp_get($tokyo); // 1677807000 (32400s = 9h earlier in UTC)

10:30 в Токио наступает на 9 часов раньше 10:30 по UTC, поэтому его метка времени меньше на 32400 секунд. О настройке часового пояса по умолчанию см. date_default_timezone_set().

Использование метки времени в вычислениях

Главная ценность метки времени — арифметика: как только дата представлена простым целым числом, её можно вычитать, сравнивать и преобразовывать без ограничений:

<?php
$start = date_timestamp_get(date_create('2023-03-03 10:30:00'));
$end   = date_timestamp_get(date_create('2023-03-03 12:00:00'));

$diffSeconds = $end - $start;
echo $diffSeconds / 60 . " minutes elapsed"; // 90 minutes elapsed

Чтобы преобразовать метку времени обратно в форматированную строку, передайте её в date() или создайте новый объект с помощью setTimestamp(). Для более сложных вычислений разницы дат (годы, месяцы, дни) лучше использовать date_diff().

Распространённые случаи применения и подводные камни

• Хранение дат в базе данных в виде целого числа ускоряет сортировку и запросы по диапазону, а также исключает зависимость от часового пояса.
• Сравнение двух моментов сводится к простому сравнению целых чисел, как только оба преобразованы в метки.
• Подводный камень — float vs int: возвращаемый тип — int. Если нужна точность до микросекунд (заданных через конструктор или date_create() с дробными секундами), getTimestamp() их обрежет; вместо этого используйте format('U.u').
• Подводный камень — даты до 1970 года дают отрицательные метки, что допустимо, но может удивить код, рассчитывающий на положительное число.
• Обратная операция: чтобы задать время объекта по метке времени, используйте date_timestamp_set().

Заключение

date_timestamp_get() предоставляет разработчикам PHP простой и точный способ свести объект DateTime к единственной UTC Unix-метке времени — идеальной для хранения, сравнения и арифметики. В повседневном объектно-ориентированном коде предпочтительнее использовать $date->getTimestamp(); обе формы взаимозаменяемы.

Практика