PHP Функция date_timezone_get()

Функция date_timezone_get() возвращает часовой пояс, привязанный к объекту DateTime, в виде объекта DateTimeZone. Знание того, какой часовой пояс несёт дата, — это разница между меткой времени, означающей «15:00 в Нью-Йорке», и той, что означает «15:00 где-то неизвестно» — и ошибка здесь является одним из самых распространённых источников ошибок «на несколько часов» в PHP-приложениях.

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

Работа с часовыми поясами в PHP

Часовой пояс — это географический регион, использующий одинаковое стандартное время. Каждый пояс идентифицируется уникальным именем IANA, например America/New_York или Europe/London. PHP поставляется с полной базой данных IANA; перечислить все поддерживаемые имена можно с помощью timezone_identifiers_list().

Каждый объект DateTime внутренне хранит часовой пояс. Если пояс не указан явно, используется стандартный пояс скрипта — значение, установленное date_default_timezone_set() (или, если это не задано, директива date.timezone в php.ini). Чтобы изменить часовой пояс существующего объекта вместо его чтения, используйте date_timezone_set().

Важный момент: date_timezone_get() не конвертирует время. Она лишь сообщает метку часового пояса, привязанную к объекту в данный момент. Чтобы фактически сдвинуть показания часов в другой пояс, нужно изменить часовой пояс с помощью setTimezone() / date_timezone_set().

Функция date_timezone_get()

date_timezone_get() является процедурным псевдонимом метода DateTime::getTimezone(). Оба делают одно и то же — возвращают экземпляр DateTimeZone, хранимый объектом DateTime (или DateTimeImmutable).

Синтаксис

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

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

$object->getTimezone();

Параметры

• $object: Объект DateTime или DateTimeImmutable, из которого нужно прочитать часовой пояс.

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

При успехе возвращает объект DateTimeZone. При ошибке возвращает false (например, если к объекту не привязана информация о часовом поясе). Вызовите getName() на результате, чтобы получить строку IANA, например "Europe/London".

Примеры

Ниже приведены примеры использования функции date_timezone_get():

Пример 1: Получение часового пояса текущей даты и времени

Объект DateTime, созданный без явного часового пояса, наследует стандартный пояс скрипта, поэтому вывод здесь соответствует тому, что было передано в date_default_timezone_set() — в данном примере UTC.

Пример 2: Получение часового пояса после его изменения

После того как setTimezone() переназначает пояс, date_timezone_get() возвращает новое значение — America/New_York.

Пример 3: Чтение смещения и конвертация между поясами

Поскольку date_timezone_get() возвращает полноценный объект DateTimeZone, его можно передавать в другие вызовы, работающие с часовыми поясами, — например, для чтения смещения UTC или конвертации момента времени из одного пояса в другой:

<?php
// 9:00 AM in London on a summer date (BST, UTC+1)
$london = new DateTime('2023-07-01 09:00:00', new DateTimeZone('Europe/London'));

$tz = date_timezone_get($london);
echo $tz->getName(), "\n";                  // Europe/London
echo $tz->getOffset($london) / 3600, "\n";  // 1  (hours east of UTC)

// Convert the same instant to Tokyo time
$london->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i'), "\n";    // 2023-07-01 17:00

Момент времени одинаков; меняется лишь отображение на часах — 09:00 по BST в Лондоне соответствует 17:00 по JST в Токио. Символы форматирования, используемые выше, описаны в date_format().

Частые ошибки

• Чтение, а не конвертация. date_timezone_get() только возвращает привязанный пояс. Присвоение результата другой переменной не изменит дату — для этого используйте setTimezone().
• Стандартный пояс vs. явный пояс. Объект, созданный без указания часового пояса, наследует стандартный пояс скрипта. Если этот стандарт задан неверно, все чтения выглядят корректными, но реальное время будет неверным. Устанавливайте его один раз с помощью date_default_timezone_set().
• Предпочитайте ООП-форму в современном коде. $object->getTimezone() — это тот же вызов, и он выглядит более естественно внутри цепочек методов.

Заключение

date_timezone_get() возвращает DateTimeZone, привязанный к объекту DateTime, предоставляя имя IANA и инструменты для чтения смещений или конвертации между поясами. В сочетании с date_default_timezone_set() и date_timezone_set() это позволяет хранить временные метки без неоднозначности для пользователей и серверов, находящихся в разных частях мира.

Практика