timezone_name_from_abbr()

Введение

В этой статье мы рассмотрим синтаксис, параметры и возвращаемое значение функции PHP timezone_name_from_abbr(), а также практические примеры её использования.

Понимание функции PHP timezone_name_from_abbr()

Функция timezone_name_from_abbr() в PHP возвращает полное имя часового пояса IANA (например, America/New_York), соответствующее заданному сокращению (например, EST). В случае успеха она возвращает имя часового пояса, а в случае неудачи — false.

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

Примечание: Эта функция печально известна своейненадёжностью, поскольку многие сокращения часовых поясов неоднозначны или нестандартны — EST, IST и CST каждое соответствует нескольким регионам мира. Руководство PHP рекомендует использовать DateTimeZone в производственных приложениях. При использовании timezone_name_from_abbr() всегда указывайте параметр $gmtOffset, чтобы PHP мог устранить неоднозначность между поясами, использующими одно сокращение.

Синтаксис

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

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

<?php

string|false timezone_name_from_abbr(string $abbr, int $gmtOffset = -1, int $isdst = -1)

Параметры

Функция принимает три параметра:

• $abbr — Сокращённое название часового пояса (например, EST или CEST). Нечувствительно к регистру.
• $gmtOffset — Смещение GMT часового пояса в секундах (не в часах). Этот параметр необязателен, но настоятельно рекомендуется. Если не указан (-1), PHP угадывает только на основе $abbr, что может вернуть false или неверный часовой пояс из-за неоднозначных сокращений.
• $isdst — Флаг, указывающий, действует ли летнее время: 1 для летнего времени, 0 для стандартного, -1 (по умолчанию) — игнорировать. При указании учитываются только пояса, соответствующие данному состоянию летнего времени.

Удобный способ вычислить смещение в секундах — умножить часы на 3600 — например, UTC−5 равно -5 * 3600 = -18000.

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

Функция timezone_name_from_abbr() возвращает имя часового пояса (строку вида America/New_York) в случае успеха или false в случае неудачи, когда ни один пояс не соответствует заданному сокращению и смещению.

Примеры

Рассмотрим несколько практических примеров использования функции timezone_name_from_abbr() в PHP.

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

В приведённых примерах мы передаём сокращённые названия часовых поясов EST и PST вместе с соответствующими смещениями GMT в секундах. Функция возвращает полные названия часовых поясов: America/New_York и America/Los_Angeles соответственно. Всегда проверяйте результат на false, чтобы обрабатывать случаи нераспознанных сокращений.

Результат можно напрямую передать в DateTimeZone для выполнения операций с датами:

<?php

$name = timezone_name_from_abbr('CET', 3600);     // "Europe/Berlin"
$date = new DateTime('2024-01-15 12:00', new DateTimeZone($name));
echo $date->format('Y-m-d H:i T'); // outputs "2024-01-15 12:00 CET"

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

• timezone_abbreviations_list() — выводит список всех известных PHP сокращений с указанием смещений и названий поясов.
• timezone_identifiers_list() — возвращает все допустимые идентификаторы часовых поясов IANA.
• date_default_timezone_set() — устанавливает часовой пояс по умолчанию для всех функций даты/времени.

Заключение

Мы рассмотрели синтаксис и использование функции PHP timezone_name_from_abbr(). Эта функция позволяет преобразовывать сокращённые названия часовых поясов в полные идентификаторы, однако из-за неоднозначности сокращений всегда следует указывать $gmtOffset и отдавать предпочтение DateTimeZone в надёжных приложениях. Надеемся, эта статья была полезной.

Практика