Функция cot_timezone_transitions в Cotonti

Описание функции cot_timezone_transitions в Cotonti, -  анализирует переходы между зимним и летним временем (DST) для указанного часового пояса и возвращает информацию о предыдущем, текущем и следующем переходах в этом часовом поясе.
Это полезно для проверки, активно ли летнее время в данный момент.

/**
 * Returns previous, current and next transition in a certain timezone.
 * Useful for detecting if DST is currently in effect.
 *
 * @param string $tz Timezone identifier, must be one of PHP supported timezones
 * @return array Multidimensional array with keys 'previous', 'current' and 'next',
 *  each containing an element of the result of DateTimeZone::getTransitions
 * @see http://www.php.net/manual/en/datetimezone.gettransitions.php
 */
function cot_timezone_transitions($tz)
{
	global $sys;
	try
	{
		$dtz = new DateTimeZone($tz);
	}
	catch(Exception $e)
	{
		return null;
	}
	$transitions = array_reverse((array)$dtz->getTransitions());
	foreach ($transitions as $key => $transition)
	{
		if ($transition['ts'] < $sys['now'])
		{
			return array(
				'previous' => $transitions[$key+1],
				'current' => $transition,
				'next' => $transitions[$key-1],
			);
		}
	}
}

Аргументы:
$tz (string): Идентификатор часового пояса (например, "Europe/Moscow" или "America/New_York"), который поддерживается PHP.
Возвращаемое значение:
Массив: Возвращает многомерный массив, содержащий информацию о предыдущем, текущем и следующем переходах (переходах на летнее/зимнее время):
'previous': Переход в зимнее или летнее время, который произошел до текущего времени.
'current': Переход, который происходит в данный момент (если он есть).
'next': Переход, который произойдет после текущего времени.
Каждый элемент массива — это результат метода DateTimeZone::getTransitions, который возвращает временные метки (timestamps) переходов, а также метки о том, является ли переход переходом на летнее время (DST).

Подробный разбор

Создание объекта DateTimeZone:

 
$dtz = new DateTimeZone($tz);

Сначала создается объект DateTimeZone для переданного часового пояса $tz. Если часовой пояс некорректен, будет сгенерировано исключение, и функция вернет null.

Получение переходов и их реверс:

 
$transitions = array_reverse((array)$dtz->getTransitions());

Метод getTransitions возвращает массив всех переходов в данном часовом поясе (например, когда начинается или заканчивается летнее время). Он возвращает эти данные в хронологическом порядке. Затем массив переворачивается (с помощью array_reverse), чтобы последние переходы были первыми для удобства дальнейшей обработки.

Поиск текущего перехода:

 
foreach ($transitions as $key => $transition)
{
    if ($transition['ts'] < $sys['now'])
    {
        return array(
            'previous' => $transitions[$key+1],
            'current' => $transition,
            'next' => $transitions[$key-1],
        );
    }
}

Функция проходит по всем переходам, чтобы найти тот, который произошел до текущего момента ($sys['now']).
Когда такой переход найден:

'previous': переход, который произошел раньше текущего.
'current': текущий переход.
'next': переход, который произойдет в будущем.

Возврат данных:

Функция возвращает ассоциативный массив с информацией о трех переходах:

previous — предшествующий переход.
current — текущий переход.
next — следующий переход.

Пример использования

Предположим, что мы хотим узнать переходы для часового пояса "Europe/Moscow". Тогда вызов функции будет следующим:

 
$transitions = cot_timezone_transitions('Europe/Moscow');
print_r($transitions);

Результат может выглядеть так:

 
Array
(
    [previous] => Array
        (
            [ts] => 1681448400
            [offset] => 10800
            [isdst] => 1
            [abbr] => MSK
        )
    [current] => Array
        (
            [ts] => 1683537600
            [offset] => 10800
            [isdst] => 1
            [abbr] => MSK
        )
    [next] => Array
        (
            [ts] => 1686129600
            [offset] => 14400
            [isdst] => 0
            [abbr] => MSK
        )
)

Пояснение к результату:

previous: Переход в летнее время (isdst = 1), произошел раньше.
current: Текущий переход в летнее время.
next: Следующий переход в зимнее время (isdst = 0).

Возможные ошибки:

Некорректный часовой пояс:
Если передан неверный или неподдерживаемый часовой пояс, функция вернет null.

Отсутствие данных:
Если нет переходов или временная зона не имеет изменений, функция не вернет ожидаемого массива.

Применение:

Функция полезна для:

Определения, активно ли летнее время в данный момент.
Вычисления точных временных переходов для обработки времени (например, для календарных событий или учета смещений времени).