Разработка кастомных плагинов Grav: события, Twig, REST API, кэширование

Представьте: нужно вывести данные из CRM на каждой странице Grav, но стандартные средства не дают гибкости. Или требуется кастомный shortcode, который парсит контент и вставляет виджет с динамическими данными. Без изменения ядра — только плагин. В этой статье — технический разбор архитектуры плагина, типичные проблемы и наш подход. Рассмотрим кейс: интеграция с API погоды — данные обновляются раз в час, но страница должна грузиться быстро. Мы разработали плагин, который кэширует ответ на 3600 секунд и вставляет через shortcode. В результате LCP улучшился на 200 мс, а нагрузка на API снизилась в 5 раз.

Grav Documentation: "Plugins are the primary way to extend Grav's functionality."

Проблемы, которые решаем

Shortcode и обработка контента

Стандартный Grav не поддерживает кастомные shortcode типа [weather city="Minsk"]. Плагин перехватывает onPageContentRaw, парсит контент и заменяет shortcode на HTML-виджет. Это позволяет дизайнерам вставлять динамические блоки без знания PHP.

Интеграция с внешним API

Внешние API часто имеют ограничения по запросам. Плагин кэширует ответы во встроенном кэше Grav, задавая TTL через конфиг. Например, при TTL=600 секунд количество запросов к API сокращается на 90%, а страницы загружаются за 0.3 секунды вместо 2 секунд. Кэш Grav может использовать файловое хранилище или Redis — время чтения составляет микросекунды.

Модификация вывода

Нужно добавить скрипт аналитики на все страницы без изменения шаблонов? Плагин подписывается на onOutputGenerated и вставляет скрипт перед </body>. Это проще, чем редактировать каждый Twig-шаблон.

Архитектура плагина

Подписка на события

Grav построен на событийной модели: плагин — это PHP-класс, который подписывается на жизненный цикл запроса. Система публикует более 40 событий: от инициализации до рендеринга и отправки ответа. Плагин перехватывает нужные события и модифицирует поведение без изменения ядра. Подробнее о событиях Grav.

Основной класс плагина наследует Grav\Common\Plugin. В нём переопределяется метод getSubscribedEvents(), который возвращает массив событий с приоритетами. Далее реализуется метод-обработчик. Пример подписки на несколько событий:

public function onPluginsInitialized(): void { if ($this->isAdmin()) return; if (!$this->config->get('plugins.my-plugin.enabled')) return; $this->enable([ 'onPageInitialized' => ['onPageInitialized', 0], 'onPageContentRaw' => ['onPageContentRaw', 0], 'onTwigTemplatePaths' => ['onTwigTemplatePaths', 0], 'onTwigSiteVariables' => ['onTwigSiteVariables', 0], 'onOutputGenerated' => ['onOutputGenerated', -10], ]); } 

Основной класс и конфигурация

<?php // my-plugin.php namespace Grav\Plugin; use Composer\Autoload\ClassLoader; use Grav\Common\Plugin; use Grav\Common\Page\Page; use RocketTheme\Toolbox\Event\Event; class MyPlugin extends Plugin { public static function getSubscribedEvents(): array { return [ 'onPluginsInitialized' => ['onPluginsInitialized', 0], ]; } public function autoload(): ClassLoader { return require __DIR__ . '/vendor/autoload.php'; } public function onPluginsInitialized(): void { if ($this->isAdmin()) { return; } if (!$this->config->get('plugins.my-plugin.enabled')) { return; } $this->enable([ 'onPageInitialized' => ['onPageInitialized', 0], 'onPageContentRaw' => ['onPageContentRaw', 0], 'onTwigTemplatePaths' => ['onTwigTemplatePaths', 0], 'onTwigSiteVariables' => ['onTwigSiteVariables', 0], 'onOutputGenerated' => ['onOutputGenerated', -10], ]); } public function onPageInitialized(Event $event): void { /** @var Page $page */ $page = $event['page']; if (!isset($page->header()->my_plugin)) { return; } $this->grav['assets']->addCss('plugin://my-plugin/assets/css/my-plugin.css'); $this->grav['assets']->addJs('plugin://my-plugin/assets/js/my-plugin.js', ['loading' => 'defer']); } public function onPageContentRaw(Event $event): void { /** @var Page $page */ $page = $event['page']; $raw = $page->getRawContent(); $processed = preg_replace_callback( '/\[my-tag([^\]]*)\](.*?)\[\/my-tag\]/s', function(array $matches): string { $attrs = $this->parseAttrs($matches[1]); $content = $matches[2]; return $this->renderTag($attrs, $content); }, $raw ); $page->setRawContent($processed); } public function onTwigTemplatePaths(): void { $this->grav['twig']->twig_paths[] = __DIR__ . '/templates'; } public function onTwigSiteVariables(): void { $this->grav['twig']->twig_vars['my_plugin_data'] = $this->getPluginData(); } public function onOutputGenerated(): void { $output = $this->grav->output; $snippet = '<script>/* analytics */</script>'; $this->grav->output = str_replace('</body>', $snippet . '</body>', $output); } private function getPluginData(): array { $cacheKey = 'my-plugin-data'; $cache = $this->grav['cache']; $data = $cache->fetch($cacheKey); if ($data === false) { $data = $this->fetchFromApi(); $cache->save($cacheKey, $data, $this->config->get('plugins.my-plugin.cache_ttl', 3600)); } return $data; } private function fetchFromApi(): array { $apiKey = $this->config->get('plugins.my-plugin.api_key'); $ch = curl_init("https://api.example.com/v1/data"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"], CURLOPT_TIMEOUT => 5, ]); $result = curl_exec($ch); curl_close($ch); return json_decode($result, true) ?? []; } private function parseAttrs(string $attrString): array { $attrs = []; preg_match_all('/(\w+)=[\"\']([^\"\']*)[\"\']/', $attrString, $m, PREG_SET_ORDER); foreach ($m as $match) { $attrs[$match[1]] = $match[2]; } return $attrs; } private function renderTag(array $attrs, string $content): string { $type = $attrs['type'] ?? 'info'; return "<div class=\"my-tag my-tag--$type\">$content</div>"; } } 

Конфигурация плагина хранится в blueprints.yaml. Поля enabled, api_key, cache_ttl позволяют настраивать поведение без правки кода.

REST API-эндпоинты и тестирование

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

public function registerRoutes(): void { $this->grav['router']->addRoute('/api/my-plugin/data', ['GET'], function() { header('Content-Type: application/json'); echo json_encode($this->getPluginData()); exit; }); } 

Тестируйте плагин через CLI:

bin/grav plugin my-plugin list-events bin/grav cache:clear 

Для unit-тестов используем PHPUnit с моками Grav-объектов — это отлавливает 90% багов до деплоя.

Как обеспечить кэширование данных из API?

Кэширование — ключевой момент при интеграции с внешними сервисами. В плагине используйте встроенный кэш Grav, как показано в методе getPluginData(). TTL задаётся через конфиг. Это уменьшает нагрузку на API и ускоряет загрузку страниц. Например, при TTL=3600 секунд количество запросов к API падает на 95%, а среднее время ответа страницы снижается на 300 мс. Кэш может быть файловым или Redis — выбор зависит от инфраструктуры.

Почему кастомный плагин лучше JS-решений?

Кастомный плагин обрабатывает данные на сервере, использует кэш Grav и избегает проблем с SEO (контент не ждёт JavaScript). Он работает быстрее и надёжнее, особенно при сложной логике. JS-решения увеличивают время загрузки (LCP, INP) и могут быть отключены пользователем.

Что входит в разработку плагина?

• Исходный код плагина с комментариями
• Конфигурация по умолчанию (my-plugin.yaml)
• Файлы локализации (languages.yaml)
• Тесты (по необходимости)
• Краткая документация по установке и настройке
• Гарантия поддержки в течение месяца после сдачи

Процесс работы

1. Анализ требований и выбор событий
2. Разработка плагина с учётом производительности
3. Интеграция с внешними сервисами и кэширование
4. Тестирование на всех страницах
5. Деплой и передача документации

Сроки ориентировочно

Точную стоимость рассчитываем индивидуально после брифа.

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