timezone_name_get()

Введение

В этой статье рассматривается функция timezone_name_get в PHP. Мы изучим её синтаксис, параметры и возвращаемые значения, а также разберём реальные примеры применения. Эта функция считывает идентификатор из объекта DateTimeZone, что удобно, когда вы сохраняете объект часового пояса и впоследствии вам нужно его имя для логирования, отображения или сравнения.

timezone_name_get является процедурным псевдонимом метода DateTimeZone::getName. Оба варианта взаимозаменяемы — выбирайте тот стиль, который лучше подходит для вашего кода.

Доступность: timezone_name_get входит во встроенное расширение PHP для работы с датой и временем. Функция всегда доступна — дополнительных расширений (например, intl) устанавливать не нужно.

Синтаксис

Функция timezone_name_get принимает единственный объект DateTimeZone и возвращает название представляемого им часового пояса. Вот её сигнатура:

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

timezone_name_get(DateTimeZone $object): string

Разберём параметры:

• $object: объект DateTimeZone, представляющий часовой пояс.

Параметры

Как упоминалось выше, функция timezone_name_get принимает только один параметр — объект DateTimeZone. Этот объект представляет конкретный часовой пояс и создаётся с помощью класса DateTimeZone. Пример создания объекта DateTimeZone:

Пример создания объекта DateTimeZone в PHP

<?php

$timezone = new DateTimeZone('America/New_York');

В этом примере мы создаём объект DateTimeZone, представляющий восточный часовой пояс США.

Примечание: в PHP 8+ применяется строгая проверка типов. Передача аргумента, не являющегося объектом DateTimeZone, вызовет исключение TypeError.

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

Функция timezone_name_get возвращает строку с названием часового пояса, представленного объектом DateTimeZone, переданным в качестве параметра. Пример использования:

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

В этом примере мы создаём объект DateTimeZone, представляющий восточный часовой пояс, и передаём его в функцию timezone_name_get. Функция возвращает строку "America/New_York", которую мы выводим с помощью оператора echo.

Функция всегда возвращает канонический идентификатор, с которым был создан объект. Если объект создан на основе смещения или аббревиатуры, возвращаемое имя отражает это:

Имена для зон на основе смещения и аббревиатуры

<?php

echo timezone_name_get(new DateTimeZone('+05:00')), PHP_EOL; // Output: +05:00
echo timezone_name_get(new DateTimeZone('GMT')), PHP_EOL;    // Output: GMT
echo timezone_name_get(new DateTimeZone('UTC')), PHP_EOL;    // Output: UTC

Для именованных зон результат представляет собой ту же строку, которую можно передать в такие функции, как date_default_timezone_set, что делает её безопасным идентификатором для двунаправленного преобразования.

Реальные примеры

Теперь, разобрав основы функции timezone_name_get, рассмотрим реальные примеры её применения.

Пример 1: Отображение часовых поясов в выпадающем меню

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

Отображение часовых поясов в выпадающем меню в PHP

<select name="timezone">
  <?php foreach(DateTimeZone::listIdentifiers() as $timezone): ?>
    <option value="<?php echo $timezone; ?>">
      <?php echo $timezone; ?>
    </option>
  <?php endforeach; ?>
</select>

В этом примере мы используем метод listIdentifiers класса DateTimeZone, чтобы получить список всех доступных часовых поясов. Поскольку listIdentifiers уже возвращает канонические имена часовых поясов, мы можем напрямую использовать $timezone как для значения, так и для метки, что делает код более эффективным.

Пример 2: Преобразование даты в другой часовой пояс

Предположим, у нас есть дата в тихоокеанском часовом поясе и нам нужно преобразовать её в восточный. Для этого можно использовать класс DateTime вместе с DateTimeZone и функцией timezone_name_get. Пример:

Преобразование даты в другой часовой пояс в PHP

В этом примере мы создаём объект DateTime, представляющий дату и время в тихоокеанском часовом поясе с использованием идентификатора America/Los_Angeles. Затем создаём его копию и с помощью метода setTimezone преобразуем в восточный часовой пояс, используя идентификатор America/New_York. Наконец, выводим даты в обоих часовых поясах с помощью метода format и проверяем активные названия часовых поясов через timezone_name_get.

Обратите внимание: восточное время показывает 12:00:00, тогда как тихоокеанское — 09:00:00 — разница ровно три часа, что полностью соответствует ожиданиям.

Объектно-ориентированная альтернатива

Поскольку timezone_name_get является просто обёрткой над DateTimeZone::getName, можно вызывать метод напрямую:

Процедурный и объектно-ориентированный стиль

<?php

$timezone = new DateTimeZone('Europe/Berlin');

echo timezone_name_get($timezone), PHP_EOL; // Procedural
echo $timezone->getName(), PHP_EOL;          // Object-oriented
// Both output: Europe/Berlin

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

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

• timezone_open — создать объект DateTimeZone, имя которого можно впоследствии прочитать.
• date_timezone_get — получить объект DateTimeZone, прикреплённый к объекту DateTime.
• timezone_offset_get — получить смещение зоны (в секундах) от UTC для заданного момента времени.
• timezone_identifiers_list — получить список всех допустимых идентификаторов часовых поясов.

Для общего обзора см. главу PHP Timezones.

Заключение

В этой статье рассмотрена функция timezone_name_get в PHP: её синтаксис, параметры, возвращаемые значения и практические случаи применения. Она возвращает канонический идентификатор, хранящийся в объекте DateTimeZone, доступна без дополнительных расширений и является аналогом метода DateTimeZone::getName. Надеемся, что эти сведения помогут вам более надёжно работать с преобразованием часовых поясов в ваших проектах.

Практика