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

Уявіть: потрібно вивести дані з 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 — час читання становить мікросекунди. Така оптимізація дозволяє заощадити до $50 на місяць на API-запитах (при 100 000 сторінок на день).

Модифікація виведення

Потрібно додати скрипт аналітики на всі сторінки без зміни шаблонів? Плагін підписується на 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'); // Реальний API-ендпоінт залежить від проєкту $ch = curl_init("https://example.com/api/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. Деплой і передача документації

Терміни орієнтовно

Точну вартість розраховуємо індивідуально після брифу. Наша компанія має 5+ років досвіду в розробці на Grav, виконали понад 50 проєктів.

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