Функция cot_selectbox_date и даты в Cotonti

Функция cot_selectbox_date в CMS Cotonti предназначена для генерации выпадающих списков для выбора даты и времени. Эти выпадающие списки могут быть использованы на веб-странице для ввода данных о дате и времени, таких как год, месяц, день, час и минута. Функция возвращает строку с HTML-разметкой, которая представляет собой эти выпадающие списки.

Описание работы функции:

1. Параметры:
   • Функция принимает несколько параметров, позволяющих настроить как будет отображаться форма и как будет учитываться часовой пояс пользователя.
2. Логика работы:
   • Вначале функция проверяет, существует ли пользовательская функция cot_selectbox_date_custom, и если она есть, вызывает её.
   • Далее идет проверка на наличие плагинов через cot_getextplugins, которые могут влиять на результат.
   • Затем функция извлекает или рассчитывает значения для года, месяца, дня, часа и минуты, в зависимости от переданного времени в формате Unix timestamp ($utime).
   • Создаются выпадающие списки для выбора года, месяца, дня, часа и минуты.
   • Возвращается строка с HTML-разметкой, которая отображает эти списки.

Теперь давай разберём каждый параметр более детально:

Параметры функции cot_selectbox_date:

1. $utime (int) — Выбранное время (Unix timestamp):
   • Это метка времени в формате Unix (количество секунд, прошедших с 1 января 1970 года).
   • Если переданное значение равно 0, то используется значение, введенное пользователем (если оно есть), либо по умолчанию будет отображено пустое значение.
2. $mode (string, по умолчанию 'long') — Режим отображения:
   • Указывает, как будут отображаться элементы в выпадающих списках.
   • 'short' — для краткого отображения (например, для мобильных устройств или компактных форм).
   • 'long' — для длинного отображения (по умолчанию). Это более подробный формат.
3. $name (string, по умолчанию '') — Префикс имени переменной:
   • Это имя для всех элементов формы (например, date[year], date[month] и так далее).
   • Если имя содержит квадратные скобки (например, date[year]), то функция разделяет его для использования в различных частях формы.
4. $max_year (int, по умолчанию 2030) — Максимальный возможный год:
   • Устанавливает верхнюю границу для выпадающего списка выбора года.
   • Например, если установить $max_year = 2030, то максимальный год, который можно выбрать, будет 2030.
5. $min_year (int, по умолчанию 2000) — Минимальный возможный год:
   • Устанавливает нижнюю границу для выпадающего списка выбора года.
   • Например, если установить $min_year = 2000, то минимальный год, который можно выбрать, будет 2000.
6. $usertimezone (bool, по умолчанию true) — Использовать часовой пояс пользователя:
   • Указывает, следует ли учитывать часовой пояс пользователя при расчёте времени.
   • Если true, то к метке времени будет добавлено смещение часового пояса пользователя ($usr['timezone']).
   • Если false, то часовой пояс пользователя не будет учитываться, и время будет отображаться без смещения.
7. $custom_rc (string, по умолчанию '') — Кастомное имя ресурса:
   • Позволяет передать кастомный ресурс (например, если используется свой шаблон для отображения даты).
   • Если значение пустое, то будет использован стандартный ресурс (input_date или его вариант в зависимости от других параметров).

Как работает функция:

• Вычисление времени: Если метка времени $utime не равна 0, она разбивается на компоненты (год, месяц, день, час, минута). Если $utime == 0, то система пытается извлечь данные из ранее введенных значений (если они были сохранены, например, в сессии или куки).
• Создание выпадающих списков:
  • Для каждого компонента даты (год, месяц, день, час, минута) генерируется соответствующий выпадающий список с помощью функции cot_selectbox. Сначала создается список доступных значений (например, месяцы, дни месяца, часы и т. д.), затем выбирается значение по умолчанию, которое отображается на экране.
• Ресурс вывода: В зависимости от параметра $mode и других факторов, будет использоваться соответствующий HTML-шаблон для отображения. В конце функция вызывает cot_rc, который генерирует итоговую HTML-разметку с выбранными значениями для даты и времени.

Таким образом, эта функция помогает создать удобный интерфейс для ввода даты и времени на сайте с учётом всех настроек (пользовательский часовой пояс, кастомные ресурсы и т.д.).

Сам код функции (system/forms.php):

/**
* Generates date part dropdown
*
* @param int $utime Selected timestamp
* @param string $mode Display mode: 'short' or complete
* @param string $name Variable name preffix
* @param int $max_year Max. year possible
* @param int $min_year Min. year possible
* @param bool $usertimezone Use user timezone
* @param string $custom_rc Custom resource string name
* @return string
*/
function cot_selectbox_date($utime, $mode = 'long', $name = '', $max_year = 2030, $min_year = 2000, $usertimezone = true, $custom_rc = '')
{
   // Используются глобальные переменные, например, для перевода и пользовательских данных
   global $L, $R, $usr;
   // Проверка, существует ли пользовательская функция для кастомизации выбора даты
   if (function_exists('cot_selectbox_date_custom')) {
       // Если она существует, вызываем её и передаем все параметры
       return cot_selectbox_date_custom($utime, $mode, $name, $max_year, $min_year, $usertimezone, $custom_rc);
   }
   // Инициализация переменной результата
   $result = NULL;
   /* === Hook === */
   // Здесь подключаются внешние плагины, если они имеются
   foreach (cot_getextplugins('form.date') as $pl) {
       include $pl; // Включаем каждый плагин, который может повлиять на форму даты
   }
   /* ===== */
   // Если результат был изменен плагинами, возвращаем его сразу
   if ($result !== NULL) return $result;
   // Определение имени для элементов формы, если оно имеет формат "name[year]"
   $rc_name = preg_match('#^(\w+)\[(.*?)\]$#', $name, $mt) ? $mt[1] : $name;
   // Если включен учёт часового пояса, корректируем время по пользователю
   $utime = ($usertimezone && $utime > 0) ? ($utime + $usr['timezone'] * 3600) : $utime;
   // Если $utime равен 0, используем сохраненные данные (например, из сессии или куки)
   if ($utime == 0) {
       // Инициализация переменных для года, месяца, дня и времени
       list($s_year, $s_month, $s_day, $s_hour, $s_minute) = [null, null, null, null, null];
       
       // Извлекаем данные, если они были сохранены ранее
       $buffered = cot_import_buffered($name, null);
       if (is_array($buffered)) {
           $s_year   = $buffered['year'];
           $s_month  = $buffered['month'];
           $s_day    = $buffered['day'];
           $s_hour   = ($buffered['hour'] ?? 0) > 0 ? $buffered['hour'] : 1; // Если час не задан, по умолчанию 1
           $s_minute = $buffered['minute'] ?? 0; // Если минута не задана, по умолчанию 0
       }
   } else {
       // Если $utime не равен 0, разбиваем его на компоненты (год, месяц, день, час, минута)
       list($s_year, $s_month, $s_day, $s_hour, $s_minute) = explode('-', @date('Y-m-d-H-i', $utime));
   }
   // Массив месяцев с их названиями на языке сайта
   $months = [];
   $months[1] = $L['January'];
   $months[2] = $L['February'];
   $months[3] = $L['March'];
   $months[4] = $L['April'];
   $months[5] = $L['May'];
   $months[6] = $L['June'];
   $months[7] = $L['July'];
   $months[8] = $L['August'];
   $months[9] = $L['September'];
   $months[10] = $L['October'];
   $months[11] = $L['November'];
   $months[12] = $L['December'];
   // Генерация выпадающего списка для выбора года (с использованием указанного максимального и минимального года)
   $year = cot_selectbox($s_year, $name.'[year]', range($max_year, $min_year, -1));
   // Генерация выпадающего списка для выбора месяца
   $month = cot_selectbox($s_month, $name.'[month]', array_keys($months), array_values($months));
   // Генерация выпадающего списка для выбора дня месяца
   $day = cot_selectbox($s_day, $name.'[day]', range(1, 31));
   // Генерация выпадающего списка для выбора часа (от 0 до 23)
   $range = [];
   for ($i = 0; $i < 24; $i++) {
       $range[] = sprintf('%02d', $i); // Заполняем массив с часами, форматируя их в виде двух цифр
   }
   $hour = cot_selectbox($s_hour, $name.'[hour]', $range);
   // Генерация выпадающего списка для выбора минут (от 0 до 59)
   $range = [];
   for ($i = 0; $i < 60; $i++) {
       $range[] = sprintf('%02d', $i); // Заполняем массив с минутами, форматируя их в виде двух цифр
   }
   $minute = cot_selectbox($s_minute, $name.'[minute]', $range);
   // Подготовка имени ресурса для рендеринга (например, в зависимости от режима отображения)
   $rc = empty($R["input_date_{$mode}"]) ? 'input_date' : "input_date_{$mode}";
   $rc = empty($R["input_date_{$rc_name}"]) ? $rc : "input_date_{$rc_name}";
   $rc = empty($custom_rc) ? $rc : $custom_rc;
   // Генерация окончательной строки с HTML-разметкой для всех элементов даты (день, месяц, год, час, минута)
   $result = cot_rc($rc, [
       'day' => $day,
       'month' => $month,
       'year' => $year,
       'hour' => $hour,
       'minute' => $minute
   ]);
   // Возвращаем результат
   return $result;
}

разберём каждый из этих пунктов по шагам, чтобы ты мог точно понять, как работает этот код:

1. Параметры функции

Функция cot_selectbox_date принимает несколько параметров, которые позволяют настраивать поведение и внешний вид выпадающих списков для выбора даты и времени.

$utime (int) – метка времени (timestamp), которая указывает на конкретный момент времени. Это значение используется для предварительного заполнения полей формы, если оно задано. Например, если это значение равно 1635724800, оно будет соответствовать определённой дате и времени.

$mode (string) – режим отображения, который может быть short или long. Это определяет, как будет выводиться дата (сокращённая или полная версия). Например, short может показывать только месяц и год, а long – полную дату.

$name (string) – имя переменной для каждого элемента формы (год, месяц, день, час, минута). Например, если передать 'date', то в HTML-коде будет сформирован элемент с именем date[year], date[month] и т. д.

$max_year (int) – максимальный год, который можно выбрать в выпадающем списке. По умолчанию это 2030.

$min_year (int) – минимальный год, который можно выбрать в выпадающем списке. По умолчанию это 2000.

$usertimezone (bool) – флаг, указывающий, нужно ли учитывать часовой пояс пользователя. Если true, время будет скорректировано с учётом часового пояса пользователя.

$custom_rc (string) – имя кастомного шаблона для рендеринга. Если этот параметр передан, то будет использован именно он, а не стандартный.

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

2. Подключение плагинов

foreach (cot_getextplugins('form.date') as $pl) {
   include $pl;
}

cot_getextplugins – это функция, которая возвращает список плагинов, подключённых к системе через указанный хук 'form.date' -  для обработки формы даты . Эти плагины могут добавлять дополнительный функционал или модифицировать стандартное поведение.

foreach – цикл проходит по каждому подключённому плагину и подключает его с помощью include. Это позволяет расширить функциональность функции, например, добавить новые поля или обработчики.

С помощью этой механики можно динамически изменять поведение функции, подключая внешние модули без изменения самого кода.

3. Обработка метки времени

if ($utime == 0) {
   // Используем сохранённые данные
} else {
   // Разбиваем метку времени на компоненты
}

Если значение $utime равно 0, это означает, что дата не была передана, и функция должна попытаться восстановить данные из сохранённого состояния, например, из сессии или базы данных (через cot_import_buffered).

Если $utime не равно 0, то оно представляет собой метку времени, и мы используем её, чтобы извлечь год, месяц, день, час и минуту через функцию date с форматом 'Y-m-d-H-i'. Это стандартная функция PHP, которая возвращает строку с нужными компонентами времени.

Таким образом, эта логика позволяет правильно обработать ситуацию, если дата ещё не была выбрана, и использовать сохранённые данные или текущую метку времени.

4. Массив месяцев

$months[1] = $L['January'];
$months[2] = $L['February'];

Здесь создаётся массив $months, где каждому числу от 1 до 12 соответствует название месяца. 
Названия месяцев берутся из глобальной переменной $L, которая хранит переводы на разные языки для интерфейса пользователя.

Например, $L['January'] будет содержать строку с названием месяца на выбранном языке. 
Таким образом, этот массив может быть легко локализован, если нужно изменить язык интерфейса.

Массив используется позже при формировании выпадающего списка для выбора месяца, где ключи массива (1, 2, 3 и т. д.) будут значениями, а названия месяцев — отображаемыми текстами.

5. Генерация выпадающих списков

$year = cot_selectbox($s_year, $name.'[year]', range($max_year, $min_year, -1));
$month = cot_selectbox($s_month, $name.'[month]', array_keys($months), array_values($months));

Для каждого компонента даты (год, месяц, день, час, минута) создаются выпадающие списки с помощью функции cot_selectbox. Эта функция формирует HTML-разметку для элемента <select>.

Для года мы создаём список с диапазоном от $max_year до $min_year с шагом -1 (то есть, список будет отсортирован по убыванию).

Для месяца список будет содержать 12 месяцев, взятых из массива $months.

Для дня — список от 1 до 31 (все возможные дни месяца).

Для часа — список от 00 до 23 (все возможные часы).

Для минуты — список от 00 до 59 (все возможные минуты).

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

6. Рендеринг с использованием шаблонов

$rc = empty($R["input_date_{$mode}"]) ? 'input_date' : "input_date_{$mode}";
$rc = empty($R["input_date_{$rc_name}"]) ? $rc : "input_date_{$rc_name}";
$rc = empty($custom_rc) ? $rc : $custom_rc;
$result = cot_rc($rc, [
   'day' => $day,
   'month' => $month,
   'year' => $year,
   'hour' => $hour,
   'minute' => $minute
]);

Здесь формируется имя шаблона, который будет использован для рендеринга формы. Сначала проверяется, существует ли шаблон для режима $mode (input_date_short, input_date_long и т. д.) в глобальной переменной $R.

Затем, если пользователь передал имя для кастомного шаблона через $custom_rc, оно будет использовано. Если нет — будет выбран стандартный шаблон.

cot_rc – это функция, которая обрабатывает шаблон и заменяет метки в нём на реальные данные. В данном случае, она передаёт массив с данными для всех выпадающих списков (день, месяц, год, час, минута) в выбранный шаблон.

Рендеринг позволяет отобразить форму в нужном формате, основываясь на локализации и выбранных параметрах.

7. Возврат результата

return $result;

Наконец, функция возвращает строку с HTML-разметкой, которая включает все выпадающие списки для выбора даты и времени.

Этот результат будет вставлен в страницу, и пользователь сможет выбрать дату и время через эти формы.

Заключение:

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