Перейти к содержанию

Хуки событий

В предыдущей главе Урок по созданию плагина вы могли заметить, что логика нашего плагина была заключена в двух методах. Каждый из этих методов, onPluginsInitialized и onPageInitialized, соответствует хукам событий, доступным на протяжении всего жизненного цикла Grav.

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

Порядок событий

Большинство событий в Grav срабатывают в определённом порядке, и этот порядок важно понимать, если вы создаёте плагины:

  1. onFatalException (без определённого порядка, может произойти в любое время)
  2. PluginsLoadedEvent class (1.7)
  3. PluginsLoadedEvent class (1.7)
  4. onPluginsInitialized
  5. FlexRegisterEvent class (1.7)
  6. onThemeInitialized
  7. onRequestHandlerInit (1.6)
  8. onTask (1.6)
  9. onTask.{task}
  10. onAction (1.6)
  11. onAction.{action} (1.6)
  12. onBackupsInitialized
  13. onSchedulerInitialized (1.6)
  14. onAssetsInitialized
  15. onTwigTemplatePaths
  16. onTwigLoader
  17. onTwigInitialized
  18. onTwigExtensions
  19. onBuildPagesInitialized (один раз при повторной обработке страниц)
  20. onPageProcessed (каждая страница, ещё не закэшированная)
  21. onFormPageHeaderProcessed (1.6) (каждая страница, ещё не закэшированная)
  22. onFolderProcessed (для каждой найденной папки)
  23. onPagesInitialized
  24. onPageInitialized
  25. onPageContentRaw (каждая страница, ещё не закэшированная)
  26. onMarkdownInitialized
  27. onPageContentProcessed (каждая страница, ещё не закэшированная)
  28. onPageContent (вызывается при первом вызове Page::content(), даже если страница закэширована)
  29. onPageNotFound
  30. onPageAction (1.6)
  31. onPageAction.{action} (1.6)
  32. onPageTask (1.6)
  33. onPageTask.{task} (1.6)
  34. onTwigPageVariables (каждая страница, ещё не закэшированная)
  35. onHttpPostFilter (1.5.2)
  36. onTwigSiteVariables
  37. onCollectionProcessed (при запросе коллекции)
  38. onOutputGenerated
  39. onPageHeaders
  40. onOutputRendered
  41. onShutdown

Прочие события:

  1. onBlueprintCreated
  2. onTwigTemplateVariables
  3. onTwigStringVariables
  4. onBeforeDownload
  5. onPageFallBackUrl
  6. onMediaLocate
  7. onGetPageBlueprints
  8. onGetPageTemplates
  9. onFlexObjectRender (1.6)
  10. onFlexCollectionRender (1.6)
  11. onBeforeCacheClear
  12. onImageMediumSaved (ImageFile)
  13. onAfterCacheClear (1.7)
  14. onHttpPostFilter (1.7)
  15. PermissionsRegisterEventclass (1.7)

Основные хуки событий Grav

Во время обработки страницы срабатывают несколько основных хуков событий Grav:

onFatalException

Это событие может быть вызвано в любой момент, если PHP выбрасывает фатальное исключение. Сейчас его использует плагин problems, чтобы показать список возможных причин, по которым Grav выбрасывает фатальное исключение.

onPluginsInitialized

Это первое доступное событие плагина. На этот момент инициализированы следующие объекты:

  • Uri
  • Config
  • Debugger
  • Cache
  • Plugins

Совет

Плагин вообще не будет загружен, если для него задана опция enabled: false.

onAssetsInitialized

Событие означает, что менеджер ресурсов инициализирован и готов к добавлению и управлению ресурсами.

onPagesInitialized

Событие означает, что все страницы в папке user/pages Grav загружены как объекты и доступны в объекте Pages.

onPageNotFound

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

onPageInitialized

Текущая страница, запрошенная по URL, загружена в объект Page.

onOutputGenerated

Вывод обработан шаблонизатором Twig и теперь представляет собой просто строку HTML.

onPageHeaders

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

onOutputRendered

Вывод полностью обработан и отправлен на экран.

onShutdown

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

onBeforeDownload

Это новое событие передаёт объект события, содержащий file. Его можно использовать для логирования или для разрешения/запрета скачивания файла.

onGetPageTemplates

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

Пример

1
2
3
4
5
6
7
8
9
/**
 * Добавляет типы шаблонов страниц.
 */
public function onGetPageTemplates(Event $event)
{
    /** @var Types $types */
    $types = $event->types;
    $types->register('downloads');
}

Это позволяет плагину зарегистрировать шаблон (который он может предоставлять), чтобы он появился в выпадающем списке типов шаблонов страниц (например, при редактировании страницы). В примере выше добавляется тип шаблона downloads, поскольку в папке downloads есть файл downloads.html.twig.

onGetPageBlueprints

Это событие, как и onGetPageTemplates, позволяет плагину предоставлять собственные ресурсы в дополнение к ресурсам ядра и темы. В данном случае — схемы.

Пример

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
$scanBlueprintsAndTemplates = function () use ($grav) {
    // Сканировать схемы
    $event = new Event();
    $event->types = self::$types;
    $grav->fireEvent('onGetPageBlueprints', $event);

    self::$types->scanBlueprints('theme://blueprints/');

    // Сканировать шаблоны
    $event = new Event();
    $event->types = self::$types;
    $grav->fireEvent('onGetPageTemplates', $event);

    self::$types->scanTemplates('theme://templates/');
};

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

Хуки событий Twig

У Twig есть собственный набор хуков событий.

onTwigTemplatePaths

Базовые расположения путей к шаблонам заданы в объекте Twig. Если нужно добавить другие места, где Twig будет искать пути к шаблонам, используйте это событие.

Пример

1
2
3
4
5
6
7
/**
 * Добавляет папку шаблонов в путь поиска Twig.
 */
 public function onTwigTemplatePaths()
 {
     $this->grav['twig']->twig_paths[] = __DIR__ . '/templates';
 }

onTwigInitialized

На этот момент шаблонизатор Twig инициализирован.

onTwigExtensions

Основные расширения Twig загружены, но если нужно добавить собственное расширение Twig, это можно сделать с помощью этого хука.

onTwigPageVariables

Когда Twig обрабатывает страницу напрямую, то есть когда в YAML-заголовках страницы задано process: twig: true. Здесь следует добавлять в Twig переменные, которые должны быть доступны Twig во время этой обработки.

onTwigSiteVariables

Когда Twig обрабатывает всю иерархию шаблонов сайта. Здесь следует добавлять в Twig переменные, которые должны быть доступны Twig во время этой обработки.

onBuildTwigSandboxPolicy (2.0)

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

Событие передаёт те же списки разрешений, что используются в security.yaml: плоские списки для tags, filters и functions, а также список строк class/methods для methods и properties. Добавляйте в нужный список способом чтения-изменения-записи (аргументы возвращаются по значению). Оно срабатывает только при построении политики, один раз за запрос, и кэшируется, поэтому затрат на каждый рендер нет.

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

Пример

1
2
3
4
5
6
7
8
9
/**
 * Разрешает функцию Twig этого плагина внутри контента страницы в песочнице.
 */
public function onBuildTwigSandboxPolicy(Event $event)
{
    $functions = $event['functions'];
    $functions[] = 'unite_gallery';
    $event['functions'] = $functions;
}

Хуки событий коллекций

onCollectionProcessed

Если нужно манипулировать коллекцией после её обработки, это подходящий момент.

Хуки событий страниц

onBuildPagesInitialized

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

onBlueprintCreated

Используется для обработки и работы с формами.

onPageContentRaw

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

onPageProcessed

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

onMarkdownInitialized

Вызывается после инициализации Markdown. Позволяет переопределить стандартную реализацию обработки Parsedown. См. пример использования в PR, где это было добавлено.

onPageContentProcessed

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

onFolderProcessed

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

onPageFallBackUrl

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

onMediaLocate

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

onTwigLoader

Добавляет поддержку использования пространств имён вместе с двумя новыми методами класса Twig: Twig::addPath($path, $namespace) и Twig::prependPath($path, $namespace).