Представьте: нужно вывести данные из CRM на каждой странице Grav, но стандартные средства не дают гибкости. Или требуется кастомный shortcode, который парсит контент и вставляет виджет с динамическими данными. Без изменения ядра — только плагин. В этой статье — технический разбор архитектуры плагина, типичные проблемы и наш подход. Рассмотрим кейс: интеграция с API погоды — данные обновляются раз в час, но страница должна грузиться быстро. Мы разработали плагин, который кэширует ответ на 3600 секунд и вставляет через shortcode. В результате LCP улучшился на 200 мс, а нагрузка на API снизилась в 5 раз.
Установка плагина
Для установки кастомного плагина скачайте архив, распакуйте в user/plugins/my-plugin. Затем включите плагин через админку или консоль: bin/grav plugin enable my-plugin. После этого настройте параметры в user/config/plugins/my-plugin.yaml.
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) и могут быть отключены пользователем.
| Критерий | JS-виджет | Кастомный плагин |
|---|---|---|
| Влияние на LCP | +200–500 мс | 0 (серверный рендеринг) |
| SEO-индексация | Сложная | Полная |
| Управление кэшем | Отсутствует | Встроенный кэш Grav |
| Зависимость от JS | Да | Нет |
Что входит в разработку плагина?
- Исходный код плагина с комментариями
- Конфигурация по умолчанию (my-plugin.yaml)
- Файлы локализации (languages.yaml)
- Тесты (по необходимости)
- Краткая документация по установке и настройке
- Гарантия поддержки в течение месяца после сдачи
Процесс работы
- Анализ требований и выбор событий
- Разработка плагина с учётом производительности
- Интеграция с внешними сервисами и кэширование
- Тестирование на всех страницах
- Деплой и передача документации
Сроки ориентировочно
| Тип плагина | Срок |
|---|---|
| Shortcode / контентная обработка | 4–12 ч |
| Интеграция с внешним API + кэш | 1–3 дня |
| Кастомная форма с обработкой | 1–2 дня |
| REST API-эндпоинты (3–5 роутов) | 1–2 дня |
| Полный функциональный плагин с UI | 3–7 дней |
Точную стоимость рассчитываем индивидуально после брифа.
Закажите разработку кастомного плагина — оценим проект за один рабочий день. Свяжитесь с нами, чтобы обсудить задачу. Получите консультацию по интеграции или расширению функциональности. Оцените возможности Grav — закажите разработку плагина уже сегодня.