Уявіть: потрібно вивести дані з 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) і можуть бути відключені користувачем.
| Критерій | JS-віджет | Кастомний плагін |
|---|---|---|
| Вплив на LCP | +200–500 мс | 0 (серверний рендеринг) |
| SEO-індексація | Складна | Повна |
| Управління кешем | Відсутнє | Вбудований кеш Grav |
| Залежність від JS | Так | Ні |
| Вартість API-запитів на місяць (100k сторінок) | ~$200 | ~$10 (завдяки кешу) |
Що входить в розробку плагіна?
- Вихідний код плагіна з коментарями
- Конфігурація за замовчуванням (my-plugin.yaml)
- Файли локалізації (languages.yaml)
- Тести (за потреби)
- Коротка документація з встановлення та налаштування
- Гарантія підтримки протягом місяця після здачі
Процес роботи
- Аналіз вимог і вибір подій
- Розробка плагіна з урахуванням продуктивності
- Інтеграція із зовнішніми сервісами та кешування
- Тестування на всіх сторінках
- Деплой і передача документації
Терміни орієнтовно
| Тип плагіна | Термін | Вартість (USD) |
|---|---|---|
| Shortcode / обробка контенту | 4–12 год | $300–$900 |
| Інтеграція із зовнішнім API + кеш | 1–3 дні | $1200–$3600 |
| Кастомна форма з обробкою | 1–2 дні | $1200–$2400 |
| REST API-ендпоінти (3–5 роутів) | 1–2 дні | $1200–$2400 |
| Повний функціональний плагін з UI | 3–7 днів | $3600–$8400 |
Точну вартість розраховуємо індивідуально після брифу. Наша компанія має 5+ років досвіду в розробці на Grav, виконали понад 50 проєктів.
Замовте розробку кастомного плагіна — оцінимо проект за один робочий день. Зв'яжіться з нами, щоб обговорити задачу. Отримайте консультацію з інтеграції або розширення функціональності. Оцініть можливості Grav — замовте розробку плагіна вже сьогодні.