Изучаем принцип работы хуков в Cotonti CMF

Хуки (hooks) в Cotonti CMF — это механизм расширений, который позволяет подключать код в различные точки жизненного цикла системы без необходимости модификации основного кода фреймворка. Это стандартный механизм в современных фреймворках, который дает возможность разработчикам вставлять свою логику в заранее определенные места (точки подключения) — хуки.

В Cotonti CMF хуки используются для:

1. Модификации поведения системы: С помощью хуков можно изменить стандартную логику работы фреймворка. Например, можно вставить свой код в момент инициализации страницы, при авторизации пользователя, при выполнении запроса к базе данных и т.д.

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

 

$sql = $db->query("SELECT * FROM $db_groups WHERE 1 ORDER BY grp_level DESC, grp_id DESC");

    if($sql->rowCount() > 0)
    {
        /* === Hook - Part1 : Set === */
        $extp = cot_getextplugins('admin.users.row.tags');
        /* ===== */
        foreach ($sql->fetchAll() as $row)
        {
            $members[$row['grp_id']] = (empty($members[$row['grp_id']])) ? '0' : $members[$row['grp_id']];
            $grp_title = isset($L['users_grp_' . $row['grp_id'] . '_title']) ? $L['users_grp_' . $row['grp_id'] . '_title'] : htmlspecialchars($row['grp_title']);
            $grp_desc = isset($L['users_grp_' . $row['grp_id'] . '_desc']) ? $L['users_grp_' . $row['grp_id'] . '_desc'] : htmlspecialchars($row['grp_desc']);
            $t->assign(array(
                'ADMIN_USERS_ROW_GRP_TITLE_URL' => cot_url('admin', 'm=users&n=edit&g='.$row['grp_id']),
                'ADMIN_USERS_ROW_GRP_NAME' => htmlspecialchars($row['grp_name']),
                'ADMIN_USERS_ROW_GRP_TITLE' => $grp_title,
                'ADMIN_USERS_ROW_GRP_DESC' => $grp_desc,
                'ADMIN_USERS_ROW_GRP_ID' => $row['grp_id'],
                'ADMIN_USERS_ROW_GRP_COUNT_MEMBERS' => $members[$row['grp_id']],
                'ADMIN_USERS_ROW_GRP_DISABLED' => $cot_yesno[!$row['grp_disabled']],
                'ADMIN_USERS_ROW_GRP_SKIPRIGHTS' => $row['grp_skiprights'],
                'ADMIN_USERS_ROW_GRP_RIGHTS_URL' => cot_url('admin', 'm=rights&g='.$row['grp_id']),
                'ADMIN_USERS_ROW_GRP_JUMPTO_URL' => cot_url('users', 'g='.$row['grp_id'])
            ));
            /* === Hook - Part2 : Include === */
            foreach ($extp as $pl)
            {
                include $pl;
            }
            /* ===== */
            $t->parse('MAIN.ADMIN_USERS_DEFAULT.USERS_ROW');
        }
    }

Давайте разберем этот участок кода по строкам с подробными комментариями:

$sql = $db->query("SELECT * FROM $db_groups WHERE 1 ORDER BY grp_level DESC, grp_id DESC");

    Запрос к базе данных: Эта строка выполняет SQL-запрос к базе данных, чтобы получить все записи из таблицы групп (переменная $db_groups). WHERE 1 всегда истинно, то есть выборка не ограничена условиями, но сортируется по полям grp_level (по убыванию) и grp_id (по убыванию). Это позволяет получить список групп с сортировкой по уровню и идентификатору группы.

if($sql->rowCount() > 0)

    Проверка наличия данных: Здесь проверяется, есть ли хотя бы одна строка в результатах запроса. Если запрос вернул хотя бы одну запись, то условие выполняется и код в теле if будет выполнен.

/* === Hook - Part1 : Set === */
$extp = cot_getextplugins('admin.users.row.tags');
/* ===== */

    Хук 1 (Part1): Это часть кода, где происходит вызов функции cot_getextplugins(), которая получает все плагины (хук) для события 'admin.users.row.tags'. Хуки — это расширения фреймворка, которые позволяют сторонним разработчикам подключать свой код в заранее определенные места фреймворка. Здесь, хук используется для выполнения дополнительной логики, связанной с обработкой строк пользователей в админке. Результат работы хука сохраняется в переменной $extp.

foreach ($sql->fetchAll() as $row)

    Перебор результатов запроса: Функция fetchAll() возвращает все строки результата запроса как массив. foreach перебирает каждую строку и обрабатывает данные для каждой группы.

$members[$row['grp_id']] = (empty($members[$row['grp_id']])) ? '0' : $members[$row['grp_id']];

    Инициализация счетчика участников: Для каждой группы проверяется, существует ли уже ключ в массиве $members с идентификатором группы grp_id. Если нет — создается и присваивается значение '0' (то есть для этой группы еще нет участников). Если же группа уже присутствует в массиве, то значение остается прежним.

$grp_title = isset($L['users_grp_' . $row['grp_id'] . '_title']) ? $L['users_grp_' . $row['grp_id'] . '_title'] : htmlspecialchars($row['grp_title']);

    Заголовок группы: Эта строка проверяет, есть ли в массиве $L элемент с ключом users_grp_{grp_id}_title, который предполагает локализацию заголовка группы. Если такой элемент существует, то используется его значение. В противном случае, используется оригинальный заголовок группы из базы данных (через htmlspecialchars для защиты от XSS).

$grp_desc = isset($L['users_grp_' . $row['grp_id'] . '_desc']) ? $L['users_grp_' . $row['grp_id'] . '_desc'] : htmlspecialchars($row['grp_desc']);

    Описание группы: Подобным образом, эта строка проверяет наличие локализованного описания группы в массиве $L. Если локализация не найдена, используется описание группы из базы данных с экранированием специальных символов для предотвращения XSS.

$t->assign(array(
    'ADMIN_USERS_ROW_GRP_TITLE_URL' => cot_url('admin', 'm=users&n=edit&g='.$row['grp_id']),
    'ADMIN_USERS_ROW_GRP_NAME' => htmlspecialchars($row['grp_name']),
    'ADMIN_USERS_ROW_GRP_TITLE' => $grp_title,
    'ADMIN_USERS_ROW_GRP_DESC' => $grp_desc,
    'ADMIN_USERS_ROW_GRP_ID' => $row['grp_id'],
    'ADMIN_USERS_ROW_GRP_COUNT_MEMBERS' => $members[$row['grp_id']],
    'ADMIN_USERS_ROW_GRP_DISABLED' => $cot_yesno[!$row['grp_disabled']],
    'ADMIN_USERS_ROW_GRP_SKIPRIGHTS' => $row['grp_skiprights'],
    'ADMIN_USERS_ROW_GRP_RIGHTS_URL' => cot_url('admin', 'm=rights&g='.$row['grp_id']),
    'ADMIN_USERS_ROW_GRP_JUMPTO_URL' => cot_url('users', 'g='.$row['grp_id'])
));

    Присваивание переменных для шаблона: Здесь происходит подготовка данных для вывода в шаблон. Каждый элемент в массиве array() присваивается переменной, которая затем будет доступна в шаблоне. Это включает в себя:
        URL для редактирования группы.
        Название и описание группы.
        Количество участников группы.
        Статус группы (активна или нет).
        Право доступа группы.
        Другие данные, такие как URL для прав и для перехода к группе пользователей.

/* === Hook - Part2 : Include === */
foreach ($extp as $pl)
{
    include $pl;
}
/* ===== */

    Хук 2 (Part2): Это вторая часть хука, где для каждого плагина, найденного в cot_getextplugins('admin.users.row.tags'), подключается файл плагина. Это дает возможность сторонним разработчикам вставить собственный код в это место. Все плагины, которые привязаны к событию 'admin.users.row.tags', будут выполнены.

$t->parse('MAIN.ADMIN_USERS_DEFAULT.USERS_ROW');

    Рендеринг шаблона: Здесь происходит вызов метода parse() объекта шаблона $t. Этот метод использует шаблон с идентификатором 'MAIN.ADMIN_USERS_DEFAULT.USERS_ROW' и вставляет в него все данные, которые были подготовлены до этого. Таким образом, каждая строка группы будет отображена в интерфейсе администратора.

}

    Закрытие цикла foreach: Завершается перебор всех групп и обработка данных.

Ключевые моменты:

    Хуки: В коде есть два хука: один для получения плагинов, второй — для их включения. Это позволяет добавлять или изменять поведение кода без изменения основного кода.
    Подготовка данных: Все данные для отображения группы готовятся с учетом локализации и безопасности (например, htmlspecialchars для предотвращения XSS).
    Использование шаблонов: Данные передаются в шаблон, который будет их рендерить на странице.

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

Принцип работы хуков:

    Что такое хук?
    Хук — это специальное место в коде, в которое разработчик или плагин может "вставить" свой код, чтобы изменить или расширить стандартную функциональность системы, не изменяя исходного кода самой программы.

    Как это работает в коде выше?
        В коде есть два хука:
            Hook - Part1 : Set
            Hook - Part2 : Include

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

Схематическое объяснение

    Визуализация работы первого хука (Part1 - Set):

    Мы сначала выполняем SQL-запрос, получаем группы, а затем передаем все данные в шаблон.

    Но, прежде чем отправить данные в шаблон, на этапе Part1 происходит вызов функции:

$extp = cot_getextplugins('admin.users.row.tags');

Эта функция ищет все плагины, которые зарегистрированы для хука 'admin.users.row.tags'. Плагины могут быть сторонними модулями, которые хотят добавить или изменить поведение кода.

Принцип работы:

Код выполняется → Хук запускает поиск подключенных плагинов → Плагины (если есть) выполняют свой код

Визуально:

    Код основной программы
       |
       V
    Хук Part1 (cot_getextplugins('admin.users.row.tags'))
       |
       V
    Плагины (если подключены) выполняют свой код
       |
       V
    Продолжаем выполнение основного кода

    Если плагинов нет, просто продолжается выполнение основного кода. Плагины — это как "дополнительные модули", которые могут что-то изменить или добавить в процессе работы программы.

    Визуализация работы второго хука (Part2 - Include):

    После того как данные подготовлены и переданы в шаблон, в Part2 происходит включение плагинов.

foreach ($extp as $pl)
{
    include $pl;
}

Это означает, что если какие-либо плагины были найдены (они содержатся в переменной $extp), то для каждого плагина будет выполнен его код. Мы подключаем (включаем) каждый плагин и даем ему возможность выполнить какие-то действия.

Принцип работы:

Основной код исполнился → Хук запускает выполнение плагинов → Плагины выполняют свой код

Визуально:

    Основной код
       |
       V
    Хук Part2 (include плагины)
       |
       V
    Плагины подключаются и выполняют свои действия
       |
       V
    Код продолжает выполнение

    Эти плагины могут изменять, дополнять или манипулировать данными перед тем, как они будут выведены в шаблон.

Пример работы хуков на примере кода:

    Step 1: Мы делаем запрос в базу данных и получаем все группы.

    Step 2: Прежде чем обработать эти данные, мы вызываем хук Part1:
    В это время, если есть подключенные плагины (которые хотят что-то изменить), их код будет выполнен. Например, плагин может изменить, как именно данные групп будут отображаться в таблице.

    Step 3: Данные групп передаются в шаблон для вывода.

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

Простое объяснение:

Представьте, что у вас есть конвейер, который собирает продукты (в нашем случае — это данные о группах):

    Ты получаешь все продукты (группы) с базы данных.
    Прежде чем передать их на финальную сборку, ты спрашиваешь у других людей (плагинов), хотят ли они что-то добавить или изменить в этих продуктах. Если кто-то хочет — он добавляет или меняет что-то.
    После этого все данные проходят через финальный этап сборки, и они уже готовы для отображения пользователю.

Хуки — это как промежуточные точки, где другие "участники" могут вмешаться в процесс и изменить его, не меняя саму основную работу конвейера.