Кастомні плагіни для 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. Деплой — налаштування на сервері, перевірка сумісності з кешуванням.

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

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