timezone_offset_get()

Функция timezone_offset_get() в PHP возвращает смещение часового пояса в секундах относительно всемирного координированного времени (UTC) для заданного объекта DateTimeInterface. В этом руководстве рассматривается синтаксис, параметры и практическое использование функции.

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

Функция timezone_offset_get() возвращает смещение часового пояса в секундах относительно всемирного координированного времени (UTC) для указанных даты и времени. Это встроенная PHP-функция, позволяющая разработчикам работать с датами и временем в рамках конкретных часовых поясов.

Синтаксис

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

Синтаксис функции timezone_offset_get() в PHP

<?php
timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

В процедурном стиле функция принимает объект DateTimeZone и объект DateTimeInterface, для которого нужно получить смещение, и возвращает смещение в секундах. Большинство разработчиков используют объектно-ориентированный эквивалент DateTimeZone::getOffset(), который выглядит более читаемо:

<?php
$tz   = new DateTimeZone('America/Los_Angeles');
$date = new DateTime('2019-01-01 12:00:00', $tz);

// These two calls are equivalent:
$offset = timezone_offset_get($tz, $date);
$offset = $tz->getOffset($date);

Параметры

Функция timezone_offset_get() принимает два параметра:

1. $object — объект DateTimeZone, смещение которого нужно получить.
2. $datetime — объект DateTimeInterface (экземпляр DateTime или DateTimeImmutable), представляющий момент времени, для которого вычисляется смещение.

Момент времени имеет значение: из-за перехода на летнее время один и тот же часовой пояс может иметь разные смещения летом и зимой, поэтому необходимо указать функции, какой именно момент имеется в виду.

Возвращаемое значение и примечания

• Возвращаемое значение: Возвращает целочисленное смещение в секундах. Для часовых поясов западнее UTC (Америка) значение отрицательное, восточнее — положительное.
• Версия PHP: Доступна начиная с PHP 5.2.0.
• Учёт летнего времени: Смещение автоматически учитывает переход на летнее время. Для America/Los_Angeles зимняя дата возвращает -28800 (UTC-8), а летняя — -25200 (UTC-7).
• Часы, а не секунды: Чтобы перевести результат в часы, разделите на 3600 (например, -28800 / 3600 = -8).

Практическое применение

Функция timezone_offset_get() в PHP является мощным инструментом для работы с датами и временем в конкретных часовых поясах. Некоторые практические сценарии использования:

1. Отображение даты и времени в соответствии с предпочтениями часового пояса пользователя.
2. Конвертация даты и времени из одного часового пояса в другой.
3. Выполнение вычислений с датами и временем с точным учётом смещений часовых поясов.

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

Пример использования функции timezone_offset_get() в PHP:

Пример использования функции timezone_offset_get() в PHP

Январская дата не попадает в период летнего времени, поэтому смещение составляет -28800 секунд (UTC-8):

-28800

Летнее время в действии

Вызов той же функции для летней даты возвращает другое смещение, поскольку тихоокеанское летнее время соответствует UTC-7. Форматирование смещения в часах делает результат более наглядным:

<?php
$tz = new DateTimeZone('America/Los_Angeles');

foreach (['2019-01-01 12:00:00', '2019-07-01 12:00:00'] as $when) {
    $date    = new DateTime($when, $tz);
    $seconds = $tz->getOffset($date);
    $hours   = $seconds / 3600;
    echo "$when => $seconds seconds (UTC$hours)\n";
}

2019-01-01 12:00:00 => -28800 seconds (UTC-8)
2019-07-01 12:00:00 => -25200 seconds (UTC-7)

Заключение

timezone_offset_get() (и её объектно-ориентированный аналог DateTimeZone::getOffset()) позволяет получить точное смещение часового пояса от UTC в секундах для конкретного момента времени с автоматическим учётом летнего времени. Разделите результат на 3600 для получения значения в часах и не забудьте передать нужную дату, чтобы корректно обработать переход на летнее время.

Для дальнейшего изучения смотрите date_default_timezone_set() для установки часового пояса по умолчанию, timezone_name_get() для получения имени часового пояса и полный список PHP-часовых поясов.

Практика