Функция cot_build_timegap в Cotonti

Эта функция cot_build_timegap возвращает разницу во времени между двумя временными метками (timestamps) в удобочитаемом формате, например, "2 дня 5 часов". Она использует разные единицы измерения времени, такие как года, месяцы, недели, дни, часы и т. д.

/**
 * Returns time gap between two timestamps
 *
 * @param int $t1
 *    Timestamp 1 (oldest, smallest value).
 * @param int $t2
 *    Timestamp 2 (latest, largest value).
 * @param int $levels
 *    Number of concatenated units to return.
 * @param int $decimals
 *    Number of decimals to show on last level.
 * @param mixed $round
 *    Round up last level to this number of decimals.
 *    Set false to disable or null to inherit from $decimals.
 * @param string $smallestunit
 *  Key of the smallest unit to show. Any number smaller than this will return 'Less than 1 ...'.
 *  Effectively its a way to cut off $units at a certain key.
 * @return string
 */
function cot_build_timegap($t1, $t2 = null, $levels = 1, $decimals = 0, $round = null, $smallestunit = null)
{
    global $Ls, $sys;
    $units = array(
        '31536000' => $Ls['Years'],
        '2592000' => $Ls['Months'],
        '604800' => $Ls['Weeks'],
        '86400' => $Ls['Days'],
        '3600' => $Ls['Hours'],
        '60' => $Ls['Minutes'],
        '1' => $Ls['Seconds'],
        '0.001' => $Ls['Milliseconds']
    );
    if ($t2 === null)
    {
        $t2 = $sys['now'];
    }
    $gap = $t2 - $t1;
    return cot_build_friendlynumber($gap, $units, $levels, $decimals, $round, $smallestunit);
}

Параметры:

$t1 (int): Первая временная метка (самое старое значение).
$t2 (int, опционально): Вторая временная метка (самое позднее значение). Если не передано, используется текущее время ($sys['now']).
$levels (int, опционально): Количество единиц времени, которые следует вернуть. Например, если установлено значение 2, функция вернёт разницу в днях и часах, но не в минутах.
$decimals (int, опционально): Количество знаков после запятой для последнего уровня. Например, если значение 0, то дробные значения не будут показываться.
$round (mixed, опционально): Параметр округления для последнего уровня. Устанавливается как целое число или false, чтобы отключить округление.
$smallestunit (string, опционально): Ключ наименьшей единицы времени, которую следует показывать. Например, можно указать 'days', чтобы показывать только разницу в днях и игнорировать меньшие единицы (часы, минуты).

Логика работы:

Установление временной метки $t2: Если $t2 не передано, то используется текущее время из глобальной переменной $sys['now'].

Вычисление временного промежутка:

Разница во времени между двумя метками вычисляется как $gap = $t2 - $t1.

Составление массива единиц времени: Внутри функции создаётся ассоциативный массив $units, который содержит ключи в виде значений временных промежутков в секундах (например, 1 год = 31536000 секунд) и соответствующие им значения на языке локализации (например, 'Years', 'Months' и т.д.). Это позволяет отображать разницу в нужных единицах времени.

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

Пример использования в контексте Cotonti:

Пример 1: Отображение времени последнего обновления темы на форуме

'FORUMS_TOPICS_ROW_TIMEGAP' => cot_build_timegap($row['ft_updated']),

Здесь $row['ft_updated'] — это временная метка последнего обновления темы.
Функция возвращает строку вида "2 дня 5 часов" (в зависимости от разницы времени).

Пример 2: Отображение времени между двумя метками времени с дополнительными настройками

$gap_base = 1632777600; // Временная метка 1
$updated = sprintf(Cot::$L['forums_mergetime'], cot_build_timegap($gap_base, Cot::$sys['now'], 2, 0));

Здесь $gap_base — это временная метка, например, время создания форума или другого события, а $sys['now'] — текущее время. Функция вернёт строку вида "1 день 3 часа" в случае, если между временными метками прошло больше 1 дня, но меньше 2 дней.

Пример возвращаемой строки:
Для разницы в "2 дня 5 часов": "2 дня 5 часов"
Для разницы в "3 недели": "3 недели"
Для разницы в "1 год": "1 год"
Функция адаптируется в зависимости от разницы во времени и выводит наилучший формат с учётом параметров.

Примечание:
В этой функции используется функция cot_build_friendlynumber, которая обрабатывает вывод в удобочитаемом формате, включая округление и уровни точности.