Функция cot_build_timezone в Cotonti

Описание функции cot_build_timezone
Функция cot_build_timezone используется для форматирования смещения временной зоны в соответствии с ISO 8601, что позволяет выводить читаемый формат времени для различных часовых поясов.

/**
 * Returns timezone offset formatted according to ISO 8601
 *
 * @param float $offset Timezone offset in seconds or hours. Set NULL for unknown timezone.
 * @param bool $withgmt Include 'UTC' in the returned string.
 * @param bool $short Use format without minutes, like GMT+1
 * @return string Textual timezone like GMT+1:00
 */
function cot_build_timezone($offset, $withgmt = true, $short = false)
{
    $gmt = $withgmt ? 'UTC' : '';
    if (is_null($offset)) {
        return $short ? "$gmt-00" : "$gmt-00:00";
    }
    if ($offset == 0) {
        return $short ? "$gmt+00" : "$gmt+00:00";
    }
    $format = $short ? 'H' : 'H:i';
    $abs = abs($offset);
    $seconds = $abs < 100 ? $abs * 3600 : $abs; // detect hours or seconds
    $time = gmdate($format, $seconds);

    return ($offset > 0) ? "$gmt+$time" : "$gmt-$time";
}

пример №1 в контексте Cotonti CMF:

'TIMEZONE' => cot_build_timezone(
        cot_timezone_offset($user_data['user_timezone'], false, false)
    ) . ' '
    . str_replace('_', ' ', $user_data['user_timezone']),

пример №2 в контексте Cotonti CMF:

$usr['timetext'] = cot_build_timezone($usr['timezone']);

Разберем функцию cot_build_timezone и ее использование в контексте Cotonti.

Параметры:

$offset — смещение временной зоны в секундах или часах. Если значение равно NULL, то возвращается строка для неизвестной временной зоны.
$withgmt — если true, в строке будет добавлен префикс UTC. Если false, то префикс не будет добавлен.
$short — если true, формат времени будет без минут (например, GMT+1), если false — с минутами (GMT+01:00).
Возвращаемое значение:

Форматированная строка с временной зоной в виде GMT+X или UTC+X:XX, в зависимости от значений параметров.

Логика работы функции:
Если $offset == NULL, это означает, что временная зона неизвестна, и функция возвращает строку "UTC-00:00".
Если $offset == 0, это означает, что временная зона совпадает с UTC, и функция возвращает строку "UTC+00:00".

Для остальных значений:
$abs определяет абсолютное значение смещения (чтобы избежать отрицательных значений).
$seconds — вычисляется количество секунд, в зависимости от того, передан ли параметр в часах или секундах.
Форматирование происходит через функцию gmdate(), которая форматирует смещение в строку по заданному формату.
Строка возвращается с нужным знаком (+ или -) перед временем, в зависимости от значения смещения.

Пример 1 в контексте Cotonti

'TIMEZONE' => cot_build_timezone(
    cot_timezone_offset($user_data['user_timezone'], false, false)
) . ' '
. str_replace('_', ' ', $user_data['user_timezone']),

Здесь:

cot_timezone_offset($user_data['user_timezone'], false, false) — это функция (предположительно) Cotonti, которая возвращает смещение временной зоны для пользователя. Эта функция используется для вычисления смещения в секундах или часах.
cot_build_timezone(...) — на основе этого смещения формируется строка временной зоны.
str_replace('_', ' ', $user_data['user_timezone']) — это используется для отображения имени временной зоны в читаемом формате (например, Europe_Moscow превращается в Europe Moscow).
Результат: Строка вида:

UTC+3 Europe Moscow

Пример 2 в контексте Cotonti

$usr['timetext'] = cot_build_timezone($usr['timezone']);

Здесь:

$usr['timezone'] — это переменная, содержащая смещение временной зоны пользователя.
cot_build_timezone($usr['timezone']) — функция форматирует это смещение и возвращает строку с временной зоной в формате GMT+X:XX.

Результат: Строка временной зоны для пользователя в читаемом формате, например:

GMT+02:00
Пример использования:
Предположим, что для пользователя в базе данных указан часовой пояс 2 (например, Europe/Moscow):

Функция cot_build_timezone(2) вернет строку "UTC+02:00".
В более длинном формате (если используется false для параметра short) будет показано полное смещение с минутами: "UTC+02:00".
Если бы часовой пояс был NULL, то результат был бы "UTC-00:00", что обозначает, что временная зона неизвестна.