Кастомні плагіни для Kirby CMS: хуки, маршрути та Vue 3 Panel

Клієнт запускав інтернет-магазин на Kirby CMS і зіткнувся з обмеженнями: вбудовані поля не підтримували прив'язку товарів до CRM, а зображення потрібно було конвертувати в WebP. Стандартні засоби не давали гнучкості — довелося писати плагін. Такі ситуації виникають регулярно, коли бізнес-логіка виходить за рамки коробкового функціоналу.

Плагін може реалізувати інтеграцію із зовнішніми сервісами, додати кастомні поля в панель керування на Vue 3, перевизначити маршрути для API або виконувати фонові завдання через хуки. Наприклад, при публікації статті автоматично генерувати WebP-зображення та надсилати сповіщення в Telegram. І все це без зміни вихідного коду Kirby, що спрощує оновлення та знижує ризик поломок. Ми розробляємо кастомні плагіни — PHP-пакети, які розширюють ядро CMS без правки його коду. Зв'яжіться з нами для попередньої оцінки вашого проєкту.

Як розробити кастомний плагін для Kirby?

Стек: PHP 8.3, Kirby 4, Vue 3 (для Panel), Composer, Docker. Використовуємо Kirby::plugin() для реєстрації розширень. Типова структура папок включає index.php, папки lib/, templates/, assets/.

<?php // site/plugins/my-plugin/index.php use Kirby\Cms\App; use Kirby\Cms\Page; App::plugin('vendor/my-plugin', [ 'options' => [ 'cache' => true, 'apiKey' => null, ], 'fields' => require __DIR__ . '/lib/fields.php', 'methods' => require __DIR__ . '/lib/methods.php', 'routes' => require __DIR__ . '/lib/routes.php', 'hooks' => require __DIR__ . '/lib/hooks.php', 'blueprints' => require __DIR__ . '/lib/blueprints.php', 'translations' => [ 'uk' => require __DIR__ . '/lib/translations/uk.php', 'en' => require __DIR__ . '/lib/translations/en.php', ], ]); 

Як уникнути N+1 запитів і не перевантажити сервер?

Без грамотних хуків кожен запит до сторінки породжує десятки зайвих SQL-запитів. Ми реалізуємо кешування на рівні плагіна: скидаємо кеш тільки при зміні конкретної сторінки, а не всього сайту. Це знижує навантаження на сервер у 3–5 разів. В одному проєкті інтеграція з Meilisearch скоротила час пошуку з 2 секунд до 50 мс. Отримайте безкоштовну консультацію щодо вашого проєкту.

<?php // lib/hooks.php return [ 'page.create:after' => function (Page $page) { if ($page->intendedTemplate()->name() !== 'article') return; $url = urlencode(kirby()->site()->url() . '/sitemap.xml'); @file_get_contents("https://www.google.com/ping?sitemap={$url}"); }, 'page.update:after' => function (Page $newPage, Page $oldPage) { if (kirby()->cache('pages')->exists($newPage->id())) { kirby()->cache('pages')->remove($newPage->id()); } }, 'file.create:after' => function (\Kirby\Cms\File $file) { if (!$file->isImage()) return; $file->thumb(['width' => 800, 'format' => 'webp']); $file->thumb(['width' => 400, 'format' => 'webp']); }, ]; 

Як інтегрувати зовнішні API через кастомні маршрути?

Часто потрібно отримувати дані з CRM або білінгу. Через кастомні маршрути ми створюємо захищені ендпоінти, що повертають JSON або XML. В одному проєкті зробили пошук по товарах через Meilisearch — результат віддається за 50 мс замість 2 секунд. Це в 40 разів швидше стандартного пошуку.

Які користувацькі поля можна додати в панель керування?

Стандартний набір полів не завжди підходить. Ми розробляємо Vue-компоненти: colorpicker, tag-input, map-picker. Це прискорює роботу редакторів і виключає помилки введення.

<?php // lib/fields.php return [ 'colorpicker' => [ 'props' => [ 'value' => function ($value = '#000000') { return $value; }, 'presets' => function (array $presets = []) { return $presets; }, ], 'save' => function ($value): string { if (!preg_match('/^#[0-9A-Fa-f]{6}$/', $value)) { throw new \Exception('Invalid color format'); } return $value; }, ], ]; 

// assets/js/fields.js panel.plugin('vendor/my-plugin', { fields: { colorpicker: { template: ` <k-field v-bind="$props"> <input type="color" :value="value" @input="$emit('input', $event.target.value)"> <div class="presets"> <button v-for="color in presets" :key="color" :style="{ background: color }" @click="$emit('input', color)" /> </div> </k-field> `, props: { value: String, presets: Array }, }, }, }); 

Реєстрація асету в index.php: 'assets' => ['js/fields.js' => __DIR__ . '/assets/js/fields.js'].

У Kirby доступні хуки для всіх основних подій: створення, оновлення, видалення сторінок і файлів, рендеринг шаблонів, надсилання email та інші. Хуки дозволяють впровадити бізнес-логіку без зміни коду сайту. Згідно з офіційною документацією, плагіни — найкращий спосіб розширення функціоналу.

Чому кастомні плагіни кращі за модифікацію ядра?

Пряма зміна ядра Kirby призводить до проблем при оновленнях: кожен новий реліз може перезаписати ваші правки. Плагіни ж живуть у своїй ізольованій папці й використовують тільки публічне API. При правильному семантичному версіонуванні ваш плагін залишиться сумісним з новими версіями без зайвих доопрацювань. Це економить час і гроші на підтримці.

Порівняння підходів до кешування

Що входить у розробку плагіна під ключ

• Вихідний код плагіна з документацією
• Налаштування Composer-пакета (опціонально)
• Приклад використання кастомних методів і хуків
• Міграції (якщо потрібні)
• Інструкція з установки та налаштування
• Підтримка протягом місяця після деплою

Типові помилки при розробці плагінів

• Неправильна робота з кешем — скидати тільки ті записи, які змінилися.
• Ігнорування семантичного версіонування — ламає сумісність при оновленнях.
• Хардкод опцій замість використання option() — ускладнює конфігурування.

Процес роботи

1. Аналітика — вивчаємо поточну архітектуру та вимоги.
2. Проектування — визначаємо хуки, методи, поля, маршрути. Узгоджуємо з вами.
3. Реалізація — пишемо код на PHP 8.3 та Vue 3.
4. Тестування — юніт-тести ключових сценаріїв, перевірка на staging.
5. Деплой — налаштування на сервері, перевірка сумісності з кешуванням.

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

Точну оцінку дамо після аналізу вимог. Замовте розробку плагіна — ми підготуємо технічне завдання та запропонуємо оптимальне рішення.