Системные хуки Cotonti. Список и примеры. Полное руководство

Системные хуки Cotonti. Полное руководство. 

Введение 

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

Материал составлен на основе анализа 220 файлов расширений, содержащих блок [BEGIN_COT_EXT] с параметром Hooks=.... Список охватывает все хуки, объявленные в ядре, модулях и плагинах Cotonti Siena.

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

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

Терминология и классификация

Все системные хуки можно разделить на несколько крупных классов:

По источнику срабатывания:

• Ядро: standalone, module, ajax, input, global, tools, rc, admin, editor, parser, parser.last, loger.event.
• Шапка и подвал: header.first, header.main, header.tags, footer.tags.
• Админ-панель: admin.home, admin.home.mainpanel, admin.home.sidepanel, admin.config.edit.main, admin.structure.first, admin.structure.tags, admin.extrafields.first, admin.users.*, admin.page.loop.
• Структура и расширения: structure.delete.first, structure.update.done, structure.getUrl, structure.extensions, extension.install.done, extension.update.done, extension.uninstall.done, extension.getPublicUrl.
• Элементы: item.getItems, item.delete.
• Модули: index.*, page.*, users.*, forums.*, pm.*, polls.*, rss.*.
• Плагины: comments.*, search.*, statistics.*, recentitems.*, trashcan.*, tags.*, i18n.*, pfs.*, selectBox.*.

По назначению:

• Точки входа (standalone, module, ajax, input).
• Общие ловушки (global, tools, rc, admin).
• Рендеринг (header.*, footer.*, index.*, page.tags, forums.*.tags, usertags.main, pagetags.main).
• CRUD-операции (*.add.*, *.edit.*, *.delete.*).
• Запросы (*.query, *.getItems).
• Циклы (*.loop).
• Специальные (selectBox.structure, loger.event, pfs.first).

Часть I. Системные хуки общего назначения

1.1. Хук standalone

Назначение. Точка входа для плагинов, доступных по прямому URL plug.php?e=<код_плагина>. Позволяет плагину полностью управлять выводом страницы: самостоятельно выводить HTML, шапку и подвал или ограничиться только содержимым.

Где используется. Десятки плагинов: contact.php, i18n.php, recentitems.php, search.php, statistics.php, tags.php, whosonline.php. Все они вызываются при прямом обращении по plug.php?e=....

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=standalone
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// код плагина

Особенности. Плагин с хуком standalone не обязан выводить шапку и подвал — это его личный выбор. Ядро не накладывает ограничений на вывод.

1.2. Хук module

Назначение. Точка входа для модулей. Срабатывает при обращении к модулю через обычный URL (index.php?e=<код_модуля>) с учётом параметров m и a. Отличается от standalone тем, что модуль работает в контексте основной системы — с шапкой, сайдбаром и подвалом, которые подключаются ядром.

Где используется. Все штатные модули Cotonti: forums.php, index.php, page.php, pfs.php, pm.php, polls.php, rss.php, users.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=module
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');

Отличие от standalone. Модуль не выводит шапку/подвал сам — это делает ядро. standalone-плагин может выводить что угодно, включая собственные шапку и подвал.

1.3. Хук ajax

Назначение. Точка входа для обработки AJAX-запросов. Срабатывает при обращении plug.php?r=<код_плагина>. Отличается от standalone тем, что ядро не выводит шапку, подвал и любые элементы интерфейса — только результат работы плагина.

Где используется. Плагины, работающие с фронтендом через fetch/XHR: autocomplete.ajax.php, ratings.ajax.php, sitemap.ajax.php, tags.ajax.php, userimages.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=ajax
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// обработка AJAX и вывод, например, JSON
header('Content-Type: application/json');
echo json_encode($result);
exit;

1.4. Хук input

Назначение. Срабатывает в момент обработки входящих данных (GET/POST) после их импорта. Позволяет плагину вмешаться в процесс приёма данных — модифицировать, отфильтровать или перехватить.

Где используется. i18n.input.php, urleditor.input.php, whosonline.input.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=input
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// обработка входных параметров

1.5. Хук global

Назначение. Срабатывает на каждом запросе к сайту — независимо от модуля, плагина и страницы. Используется для глобальных вещей: проверки бана, установки сессий, подсчёта хитов, загрузки конфигураций, регистрации CSS/JS.

Где используется. banlist.global.php, hiddengroups.groups.php, hits.global.php, htmlpurifier.php, i18n.global.php, mcaptcha.global.php, referers.global.php, tags.global.php, whosonline.global.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=global
Order=5
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// глобальные действия

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

1.6. Хук tools

Назначение. Добавляет страницу инструментов плагина в разделе «Инструменты» (Tools) административной панели. Используется для страниц, не привязанных к конкретному разделу админки.

Где используется. autoalias2.admin.php, banlist.admin.php, contact.tools.php, hits.admin.php, ipsearch.admin.php, ratings.admin.php, referers.admin.php, tags.tools.php, trashcan.admin.php, urleditor.admin.php, userimages.admin.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=tools
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// вывод страницы инструмента

1.7. Хук rc

Назначение. Resource Consolidation — консолидация ресурсов. Срабатывает при сборке ресурсов темы (CSS, JS) в один файл. Позволяет плагинам добавлять свои файлы в консолидированный вывод.

Где используется. autocomplete.rc.php, ratings.rc.php, search.rc.php, tags.rc.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=rc
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// добавление ресурсов в консолидацию

1.8. Хук admin

Назначение. Точка входа для модулей, имеющих собственную админ-часть. Срабатывает при обращении к модулю в админке: admin.php?m=<код_модуля>.

Где используется. forums.admin.php, page.admin.php, pfs.admin.php, polls.admin.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=admin
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// админка модуля

1.9. Хук editor

Назначение. Подключение визуального редактора. Плагин, объявивший этот хук, получает возможность предоставить свой редактор для полей ввода.

Где используется. ckeditor.editor.php.

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=editor
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// инициализация редактора

1.10. Хуки парсера: parser, parser.last

Назначение. Срабатывают в момент обработки текста (постов, статей, комментариев) перед выводом. parser — основной этап, parser.last — финальный, после всех предыдущих парсеров.

Где используется. html.parser.php (хук parser), ckeditor.anchor.php (хук parser.last).

Пример объявления:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=parser.last
[END_COT_EXT]
==================== */
defined('COT_CODE') or die('Wrong URL.');
// пост-обработка текста

Часть II. Хуки шапки, подвала и общих элементов страницы

2.1. header.first

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

Где используется. pm.header.first.php.

2.2. header.main

Назначение. Основной хук формирования шапки. Срабатывает после header.first, но до header.tags. Обычно используется для добавления крупных блоков в шапку: меню, форм поиска, элементов навигации.

Где используется. page.header.php, pm.header.php, search.header.php, contact.header.php, whosonline.header.main.php.

2.3. header.tags

Назначение. Финальный хук шапки. Срабатывает после того, как все теги уже назначены шаблону. Позволяет добавить в HTML-код свои скрипты и стили, вставить мета-данные, подгрузить ресурсы.

Где используется. pfs.header.php, i18n.header.tags.php, recentitems.index.php (через составной хук), tags и другие.

2.4. footer.tags

Назначение. Хук подвала. Срабатывает при формировании нижней части страницы. Аналог header.tags для футера.

Где используется. recentitems.index.php (через составной хук index.tags,header.tags,footer.tags).

Часть III. Хуки административной панели

3.1. admin.home

Назначение. Главная страница административной панели. Срабатывает при обращении к admin.php без параметров. Позволяет добавить свой блок на дашборд.

Где используется. cleaner.php, trashcan.admin.home.php.

3.2. admin.home.mainpanel

Назначение. Основная панель на главной админки. Отдельный хук для вывода в центральную часть дашборда (не в боковую).

Где используется. comments.admin.home.php, hits.admin.home.php.

3.3. admin.home.sidepanel

Назначение. Боковая панель на главной админки.

Где используется. page.admin.home.php, users.admin.home.php.

3.4. admin.config.edit.main

Назначение. Основной блок редактирования конфигурации. Позволяет плагину добавить свои поля в форму настроек другого расширения.

Где используется. comments.admin.config.php, ratings.admin.config.php — оба подключаются к форме настройки структуры.

3.5. admin.structure.first

Назначение. Начало редактирования структуры (категорий). Позволяет плагину вмешаться в процесс до отображения формы.

Где используется. comments.admin.config.php, ratings.admin.config.php.

3.6. admin.structure.tags

Назначение. Формирование шаблона страницы структуры. Позволяет добавить в форму свои теги.

Где используется. i18n.admin.structure.php.

3.7. admin.extrafields.first

Назначение. Начало работы со списком дополнительных полей. Позволяет плагину добавить свои extrafields для отображения в админ-списке.

Где используется. Практически всеми модулями и плагинами: forums.extrafields.php, page.extrafields.php, users.extrafields.php, comments.extrafields.php, contact.extrafields.php.

3.8. Хуки admin.users.*

Группа хуков для работы с пользователями в админке:

• admin.users.add.first — перед добавлением пользователя админом.
• admin.users.add — основной этап добавления.
• admin.users.add.tags — теги формы добавления.
• admin.users.edit.tags — теги формы редактирования.
• admin.users.update — момент обновления данных.
• admin.users.row.tags — теги строки списка.

Где используется. pfs.admin.users.* (весь набор), hiddengroups.admin.users.* (весь набор).

3.9. admin.page.loop

Назначение. Цикл по страницам в админке (список статей в админ-панели). Позволяет добавить в каждую строку списка свой столбец или данные.

Где используется. tags.admin.page.loop.php.

Часть IV. Хуки структуры и расширений

4.1. structure.delete.first

Назначение. Срабатывает перед удалением категории. Позволяет плагину очистить связанные данные перед тем, как категория будет удалена.

Где используется. i18n.admin.structure.delete.php, trashcan.page.delete.php.

4.2. structure.update.done

Назначение. Срабатывает после обновления категории. Используется для реакций на изменение структуры.

Где используется. i18n.structure.update.done.php.

4.3. structure.getUrl

Назначение. Формирование URL для категории. Плагин может переопределить стандартный URL, сгенерированный ядром.

Где используется. forums.structure.getUrl.php.

4.4. structure.extensions

Назначение. Расширение списка областей структуры (модулей, использующих структуру). Позволяет добавить свой модуль в общий механизм структуры.

Где используется. forums.structure.php, page.structure.php.

4.5. extension.install.done

Назначение. Срабатывает после завершения установки любого расширения. Позволяет автоматически подписаться на установку расширений — например, создать сопутствующую таблицу или добавить права.

Где используется. comments.extension.install.done.php, i18n.extension.install.done.php, ratings.extension.install.done.php.

4.6. extension.update.done

Назначение. Срабатывает после обновления расширения.

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

4.7. extension.uninstall.done

Назначение. Срабатывает после удаления расширения.

Где используется. Потенциально всеми плагинами, которым нужно очистить данные после удаления.

4.8. extension.getPublicUrl

Назначение. Получение публичного URL для расширения. Позволяет плагину вернуть свой URL при запросе.

Где используется. page.extension.getPublicUrl.php, comments.extension.getPublicUrl.php.

Часть V. Хуки элементов и записей

5.1. item.getItems

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

Где используется. forums.posts.getItems.php, forums.topics.getItems.php, page.item.getItems.php, polls.item.getItems.php, users.item.getItems.php, comments.item.getItems.php.

Смысл. Позволяет плагину подписаться на получение элементов любого типа и вмешаться в формирование списка — добавить фильтры, изменить сортировку, дополнить данные.

5.2. item.delete

Назначение. Удаление элемента. Срабатывает в момент удаления любого универсального элемента — товара, страницы, комментария, пользователя.

Где используется. polls.item.delete.php, comments.item.delete.php, tags.item.delete.php, trashcan.item.delete.php.

Смысл. Позволяет плагинам (корзина, теги, опросы) автоматически очищать связанные данные при удалении любого элемента.

Часть VI. Хуки главной страницы

6.1. index.main

Назначение. Основная часть главной страницы. Позволяет плагину добавить свой блок в центральную область.

Где используется. indexnews.index.main.php.

6.2. index.tags

Назначение. Финальные теги главной страницы. Позволяет добавить свой HTML-код в шаблон.

Где используется. indexnews.index.tags.php, polls.index.php, recentitems.index.php, tags.index.php.

Часть VII. Хуки модуля «Страницы» (page)

Модуль page предоставляет самое большое количество хуков. Они делятся на четыре категории: добавление, редактирование, удаление, просмотр.

7.1. События добавления

• page.first— самое начало обработки запроса на добавление. Позволяет перехватить операцию до её выполнения. Используется search.page.first.php.
• page.add.tags— теги формы добавления страницы. Используется pfs.page.tags.php, tags.page.add.tags.php (с составным i18n.page.translate.tags).
• page.add.add.done— момент успешного добавления страницы. Используется autoalias2.page.php, tags.page.add.php.
• page.add.add.error— момент ошибки при добавлении. Используется tags.page.add.edit.php.

7.2. События редактирования

• page.edit.tags— теги формы редактирования. Используется pfs.page.tags.php, tags.page.edit.tags.php.
• page.edit.update.done— успешное редактирование.
• page.edit.update.error— ошибка при редактировании.

7.3. События удаления

• page.delete.first— перед удалением страницы. Используется i18n.page.delete.php, trashcan.page.delete.php.
• page.delete.done— после удаления. Используется ratings.page.delete.done.php.

7.4. Просмотр и списки

• page.main— основная часть просмотра страницы. Используется i18n.page.main.php, tags.page.main.php.
• page.tags— финальные теги страницы.
• page.list.main— основная часть списка страниц.
• page.list.loop— цикл по страницам в списке.
• page.list.query— SQL-запрос для списка.
• page.list.rowcat.loop— цикл по категориям в списке.
• page.list.tags— теги списка.

7.5. page.enum.query и page.enum.loop

• page.enum.query— SQL-запрос при перечислении страниц.
• page.enum.loop— цикл по страницам при перечислении.

7.6. page.item.getItems

Получение списка страниц через универсальный механизм item.getItems. Позволяет плагину встроиться в процесс.

Часть VIII. Хуки модуля «Пользователи» (users)

8.1. Регистрация

• users.register.tags— теги формы регистрации. Используется mcaptcha.register.tags.php.
• users.register.add.first— перед добавлением пользователя. Используется banlist.register.php, mcaptcha.register.validate.php.
• users.register.add.done— после добавления.
• users.adduser.done— альтернативный хук завершения регистрации. Используется hiddengroups.users.register.add.done.php.

8.2. Профиль и редактирование

• users.profile.tags— теги формы профиля.
• users.profile.update.first— перед обновлением профиля.
• users.edit.tags— теги формы редактирования.
• users.edit.update.first— перед обновлением через админку.
• users.edit.update.done— после обновления.

8.3. Удаление и выход

• users.delete— удаление пользователя. Используется trashcan.user.delete.php.
• users.logout— выход пользователя. Используется whosonline.users.logout.php.

8.4. Авторизация

• users.auth.check.done— после успешной авторизации. Используется whosonline.users.auth.check.done.php.

8.5. Списки и фильтры

• users.filters— фильтры в списке пользователей.
• users.query— SQL-запрос списка пользователей.

Часть IX. Хуки модуля «Форумы» (forums)

9.1. Создание темы

• forums.newtopic.first— перед созданием новой темы.
• forums.newtopic.newtopic.first— внутри процесса создания.
• forums.newtopic.newtopic.done— после создания.
• forums.newtopic.tags— теги формы создания.

9.2. Редактирование поста

• forums.editpost.first— перед редактированием поста.
• forums.editpost.update.first— перед обновлением.
• forums.editpost.update.done— после обновления.
• forums.editpost.tags— теги формы.

9.3. Просмотр постов

• forums.posts.first— начало просмотра постов.
• forums.posts.main— основная часть просмотра.
• forums.posts.tags— финальные теги.
• forums.topics.first— начало просмотра тем.
• forums.topics.loop— цикл по темам.
• forums.topics.query— SQL-запрос тем.
• forums.topics.tags— теги тем.

9.4. Разделы форума

• forums.sections.main— основная часть разделов.
• forums.sections.tags— теги разделов.
• forums.sections.loop.sections— цикл по подразделам.

9.5. Удаление

• forums.topic.delete— удаление темы.
• forums.post.delete.done— удаление поста.

Часть X. Хуки комментариев и личных сообщений

10.1. Комментарии

• comments.newcomment.tags— теги формы нового комментария.
• comments.edit.tags— теги формы редактирования.
• comment.delete.done— удаление комментария.

10.2. Личные сообщения

• pm.send.tags— теги формы отправки.
• pm.reply.tags— теги формы ответа.

Часть XI. Хуки опросов, поиска, статистики

11.1. Опросы

• polls.index.tags— теги на главной.
• polls.view.tags— теги при просмотре опроса.
• polls.viewall.tags— теги общего списка опросов.

11.2. Поиск

• search.first— начало обработки поиска.
• search.list— формирование списка результатов.
• search.page.catlist— список категорий в фильтре поиска.
• search.page.loop— цикл по страницам в результатах.
• search.page.query— SQL-запрос поиска страниц.

11.3. RSS

• rss.create— создание RSS-ленты.

11.4. Статистика

• statistics.tags— теги страницы статистики.
• statistics.user— данные о пользователе в статистике.

11.5. Недавние элементы

• recentitems.recentpages.query— SQL-запрос недавних страниц.
• recentitems.recentpages.tags— теги недавних страниц.

11.6. Корзина

• trashcan.api— API корзины. Используется всеми модулями, поддерживающими восстановление: forums.trashcan.php, page.trashcan.php, comments.trashcan.php, i18n.trashcan.php.

11.7. Теги

• tags.search.pages.query— SQL-запрос поиска по тегам.
• tags.search.pages.loop— цикл по страницам при поиске по тегам.

11.8. i18n

• i18n.page.add.done— добавление перевода страницы.
• i18n.page.edit.tags— теги формы редактирования перевода.
• i18n.page.edit.update— обновление перевода.
• i18n.page.translate.tags— теги формы перевода.
• i18n.page.delete.done— удаление перевода.

Часть XII. Специальные хуки

12.1. pfs.first

Назначение. Начало работы с персональным файловым хранилищем (PFS). Позволяет плагину вмешаться в работу с файлами до основного кода.

Где используется. ckeditor.pfs.php, html.pfs.php.

12.2. selectBox.structure

Назначение. Формирование выпадающего списка категорий структуры. Позволяет плагину изменить список или добавить свои данные.

Где используется. i18n.selectBox.structure.php.

12.3. usertags.main, pagetags.main

Назначение. Основные хуки формирования пользовательских тегов для страницы пользователя и страницы контента соответственно.

Где используется. pm.usertags.php, userimages.usertags.main.php, whosonline.usertags.main.php, i18n.pagetags.php.

12.4. loger.event

Назначение. Срабатывает в момент записи в журнал (cot_log()). Позволяет изменить данные записи перед вставкой в БД.

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

Часть XIII. Порядок выполнения и приоритеты

Все хуки выполняются в порядке возрастания pl_order. Значение по умолчанию — 10. Плагин может указать в своём блоке [BEGIN_COT_EXT]:

[BEGIN_COT_EXT]
Hooks=header.main
Order=5
[END_COT_EXT]

Чем меньше число, тем раньше выполнится обработчик.

Если несколько плагинов имеют одинаковый Order, они выполняются в порядке их записи в таблице cot_plugins — обычно в порядке установки.

Для хуков, где важен порядок (например, parser и parser.last), ядро вызывает их в определённой последовательности. parser.last срабатывает после всех parser, поэтому плагины, которым нужно «финальное» слово в парсинге, подписываются именно на parser.last.

Часть XIV. Полная сводная таблица хуков

Заключение

Системные хуки Cotonti — это фундамент, на котором строится вся расширяемость движка. Каждый модуль и плагин подписывается на нужные ему хуки, объявляя их в заголовках своих файлов-обработчиков. Ядро, в свою очередь, находит эти подписки в базе данных и подключает файлы в нужных местах кода.

Понимание полного перечня системных хуков позволяет:

• администратору — видеть, какие расширения за что отвечают, и диагностировать конфликты;
• разработчику — выбирать правильные хуки для своей задачи, не создавать дублирующие решения и корректно интегрироваться с существующей архитектурой.

Руководство охватывает 130+ системных хуков, объявленных в 220 файлах расширений Cotonti Siena. Список может расширяться с появлением новых версий движка и сторонних расширений, но принципы их именования, объявления и чтения остаются неизменными.