Hook (хук в cotonti.)

Что такое хуки и как их использовать в котонти.

Что такое Hook?

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

Допустим мы взяли за основу кусок кода из файла page.main.php модуля page.

Мы имеем код движка, имеющий хук page.first(блок №1). Это означает, что в данном месте будет подключен и выполнен php файл вашего плагина со значением Hook=page.first.(блок №2) После этого интерпритатор php будет продолжать выполнять основной код движка.(блок №3) Таким образом вы можете влиять на поведение движка.

Давайте посмотрим еще пример:

Представьте себе сценарий, который имеет хук внутри.

$foo = 'Мальчик Вова';
$bar = 'играл в мяч!';
 
// ...
// Здесь хук
// ...
 
echo "$foo $bar";

Данный код выдаст строку Мальчик Вова играл в мяч!, но если хук подключит сторонний php файл, в котором, к примеру, будет вот такая строка:

$foo .= ' в новых кроссовках ';

Тогда данный код уже выдаст строку Мальчик Вова в новых кроссовках играл в мяч!

Произошла коррекция выполнения кода. В этом смысл хуков в движке котонти.

Выбор правильного хука.

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

Основные хуки

Есть несколько хуков, которые присутствуют в любом потоке и срабатывающие в той же последовательности относительно друг друга:

input — это первая точка входа в поток скрипта. В этой точке входа доступна конфигурация и структура движка, а так же расширения и пользовательские объекты, но система еще не была инициализирована полностью. Используя этто хук, можно перезаписать такие параметры как: тема / язык / ресурсы и некоторые другие параметры;
global — это для кода, который должен быть выполнен при каждом запросе, сразу после инициализации системы;
standalone — это для кода, котрый будет иметь свой отдельный адрес и отдельную страницу.
header.first — выполняется перед генерацией header страницы.
header.main — здесь можно изменить некоторые переменные в части header страницы, прежде чем они будут выданы. Эта часть игнорируется в режиме AJAX;
header.tags — здесь можно задать дополнительные теги для header в дополнение к стандартным. Также игнорируется в режиме AJAX;
footer.first — вызывается до создания части footer;
footer.main — здесь вы можете изменить некоторые переменные в footer части, прежде чем они будут выданы. Эта часть игнорируется в режиме AJAX;
footer.tags — здесь можно задать дополнительные теги для footer. Также игнорируется в режиме AJAX;
footer.last — выполняется после создания footer, независимо от того, AJAX используется или нет;
output — это последний хук, который срабатывает прямо перед генерацией страницы сайта целиком. В самом конце работы сценария. Он может быть использован для манипулирования выходных данных или удаления неких ресурсов.

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

Чтобы включить режим отладки, необходимо открыть файл datas / config.php и установить значение переменной TRUE для $cfg[‘debug_mode’]

$cfg['debug_mode'] = true;

(Примечание: эта функция работает начиная с версии Cotonti 0.9.6)

Соглашение об именах

Несколько слов о названиях хука и их значений. Большинство имен хука состоит из нескольких слов, разделенных точками.

Например:

Первое слово обычно означает модуль или основную часть, где хук существует (module/area). Например «users» означает модуль пользователи, или «header» означает часть header . Это первый намек для вас найти фактическое место в исходном коде, где находится этот хук. Следующее слово часто означает «режим» или «часть» модуля или скрипта, например ‘users.register’ означает, что хук находится в части регистрации пользователя. Это также означает, что вы, вероятно, может найти его в файле под названием users.register.php. С точки зрения MVC (Model-View-Controller) вы можете также рассмотреть этот контроллер модуля. Далее используется композитное название события или действия, которое будет происходить, а также состояние события или расположение хука (первый, последний, цикл и т.д.). В приведенном выше примере это ‘add.done’, что означает, что новый пользователь был добавлен (событие) успешно (состояние). В MVC событие / действие может быть именем метода.

Таким образом, по имени хука вы можете определить файл, где можно найти его и событие, которое он обрабатывает. Вы должны придерживаться этого соглашения при определении собственные хуков. Подробнее об этом позже.

Особый тип хука — хук loop (цикл, петля). В название такого хука обычно заканчивается на loop, например, ‘forums.topics.sections.loop’. Обычно данный хук определяется внутри цикла. Наиболее распространенным сценарием для этого находится в пределах строки результатов SQL, где хук присутствует в каждой строке множества данных.

Определение обработчика хука

Обработчик представляет собой PHP файл, который находится в папке плагина (расширения). Он имеет имя, похожее на имя хука, что он использует. Это не является обязательным требованием, но это общее соглашение по использованию имени файлов, которые соответствуют хукам, такие как myext.page.edit.update.done.php который использует page.edit.update.done хук. По сути дела плагин является набором обработчиков, собранных воедино и выполняющие одну общую функцию.

Шаблон типичного обработчика хука представлена ниже:

<?php
/* ====================
[BEGIN_COT_EXT]
Hooks=page.tags
Tags=page.tpl:{PAGE_MYEXT_TAG1},{PAGE_MYEXT_TAG2}
Order=10
[END_COT_EXT]
==================== */
 
defined('COT_CODE') or die('Wrong URL');
 
// Здесь код обработчика хука.
 
?>

Прежде всего, давайте рассмотрим заголовок (настройки между BEGIN_COT_EXT и END_COT_EXT).

Строка Hooks=page.tags указывает, какой хук будем обрабатывать.Cotonti ветки siena поддерживает и мультихуки. Это означает что вы можете указать только один хук или перечислить несколько хуков через запятую Hooks=header.tags,index.tags,page.tags,footer.tags и данный обработчик будет обрабатывать все перечисленные хуки.

Пример: Hooks=header.tags,index.tags,page.tags,footer.tags Строка присвоения хука (ов) обработчику является обязательной, другие настройки обработчика являются необязательными и могут быть опущены.

Строка Tags=page.tpl:{PAGE_MYEXT_TAG1},{PAGE_MYEXT_TAG2} используется если в коде вашего обработчика присваиваются новые теги. Цель данной настройки уведомить пользователя о новых доступных тегах и их присутствии, созданным вашим обработчиком. Эти параметры будут высвечены на странице данного плагина в панели администратора. Строку из примера можно расшифровать как — в файле page.tpl доступны новые теги {PAGE_MYEXT_TAG1} и {PAGE_MYEXT_TAG2}.

Не стоит забывать, что один и тот же хук могут использовать несколько обработчиков. Для придания приоретета на более раннее выполнения кода обработчика, имеется настройка Order=10 Данная настройка дает приоритет на порядок выполнения. Чем ниже значение order тем выше приортет. Таким образом обработчик с настройкой Order=5 будет выполнятся раньше чем обработчик с Order=50. Если данный параметр не указать явно, то он по умолчанию равен 10.

Что вы можете сделать в обработчике?

Запуск запросов к базе данных, для загрузки и манипулировать данными.
Изменить текущие переменные и объекты.
Связать теги шаблонов и разобрать шаблона блоков.

Главное, чтобы вы были в курсе области переменных. Котонти активно использует глобальные переменные. Большенство хуков расположены в глобальной области видимости переменных, так что вы можете использовать их из коробки. Некоторые хуки расположены в пределах функций, поэтому необходимо определять глобальные переменные явно в них. Наиболее часто используемые переменные $cfg, $usr, $db, $id, $strucutre, $t. Они на самом деле заслуживают еще одну статью, чтобы объяснить смысл их использования.

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

Использование хуков в ваших расширениях

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

Добавьте следуюющий код:

/* === Hook === */
foreach (cot_getextplugins('myext.hook.name') as $pl)
{
    include $pl;
}
/* ===== */

Замените myext.hook.name фактическим именем хука. Данный код можно написать в 1 линию, но мы обычно предпочитаем использовать 6-строчную конструкцию. Это делает хуки более различимыми среди окружающего кода.

Более сложная ситуация является с хуком в цикле. Обработчики такого хука выполнен на каждой итерации цикла.

Ниже приведен пример такого приема:

/* === Hook - Part1 : Set === */
$extp = cot_getextplugins('myext.some.loop');
/* ===== */
 
// It can be foreach/while/do, whatever you like
foreach ($items as $item)
{
    // Some code here
 
    /* === Hook - Part2 : Include === */
    foreach ($extp as $pl)
    {
        include $pl;
    }
    /* ===== */
 
    // Possibly some code here
}

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

Hook (хук в cotonti)