Кастомные плагины для 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' => [ 'ru' => require __DIR__ . '/lib/translations/ru.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. Деплой — настройка на сервере, проверка совместимости с кэшированием.

Сроки ориентировочно

Точную оценку дадим после анализа требований. Закажите разработку плагина — мы подготовим техническое задание и предложим оптимальное решение.