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

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

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

Headless CMS: Strapi, Directus, Sanity, Contentful, Drupal

Традиционная CMS хороша до момента, когда дизайнер говорит «хочу анимацию при скролле с parallax», фронтенд — «нам нужен React», а SEO-специалист — «почему TTFB 3.4 секунды». В этот момент монолитная архитектура начинает мешать всем сразу. Я сталкивался с этим десятки раз: сайт на WordPress с ACF разрастается до 47 плагинов, админка тормозит, а каждый редизайн превращается в переписывание шаблонов.

Headless CMS отделяет управление контентом от его представления. Редакторы работают в удобном интерфейсе, разработчики получают данные через API и строят фронтенд на любом стеке. Звучит просто. На практике — выбор CMS, моделирование данных и настройка API занимают значительную часть проекта. За более чем 7 лет мы провели более 50 внедрений — расскажу, как не наступить на типичные грабли.

Почему headless CMS выгоднее монолита?

Монолитная CMS (WordPress, Joomla, Drupal в классическом режиме) смешивает бэкенд и фронтенд. Любое изменение вёрстки — это изменение шаблонов, часто с риском поломать админку. Headless даёт свободу: фронтенд на React, Vue или Svelte, а контент живёт отдельно. Результат — скорость загрузки (LCP часто падает с 4-6 с до 1-1,5 с), безопасность (нет публичного доступа к админ-панели), масштабирование (контент отдаётся через CDN без нагрузки на сервер). Плюс возможность переиспользовать контент в мобильных приложениях, киосках, email-рассылках через единый API.

Какую headless CMS выбрать под проект?

Нет универсального инструмента. Выбор зависит от команды, сложности контента и инфраструктуры. Разберём ключевые варианты.

Strapi — open-source, self-hosted, Node.js. Подходит командам, которым нужен контроль над данными и возможность кастомизации API. Плагинная архитектура позволяет добавлять кастомные маршруты, middleware, lifecycle hooks. REST и GraphQL из коробки. Разворачивается за час — в 3 раза быстрее Drupal. Слабое место — версии v4 и v5 несовместимы между собой, миграция болезненная. Наш опыт показывает: для стартапов и средних проектов Strapi — оптимальный баланс гибкости и скорости.

Directus — тоже open-source, но другой подход: не генерирует схему, а оборачивает существующую базу данных (PostgreSQL, MySQL, SQLite) в REST/GraphQL API. Если база данных уже есть — Directus подключается к ней без миграций. Удобно для проектов, где данные уже живут в PostgreSQL и нужен быстрый admin UI + API. Экономия времени на этапе интеграции — до 30%.

Sanity — облачная CMS с real-time редактором. Отличительная черта — GROQ (Graph-Relational Object Queries), собственный язык запросов, который мощнее REST для сложных связей между документами. Portable Text для структурированного контента. Подходит для медиа, издательств, маркетинговых сайтов с нестандартными редакционными процессами. Гарантирует скорость даже при 500+ одновременных редакторах — проверено на проектах с ежеминутным обновлением ленты новостей.

Contentful — enterprise облачная CMS. Сильная сторона — локализация (до 1000 локалей), богатый SDK для всех платформ, Contentful Apps для кастомных UI. Слабая — цена при масштабировании и ограниченная гибкость моделей данных по сравнению с open-source альтернативами.

Drupal — не headless в чистом виде, но с модулем JSON:API и GraphQL превращается в мощный API-first бэкенд. Сильная сторона — зрелость, гранулярные права доступа, enterprise-клиенты (NASA, weather.com). Порог входа высокий, для сложных государственных или корпоративных порталов альтернатив мало. Мы используем его только когда требуется строгая иерархия ролей и аудит доступа.

Последствия неправильного моделирования контента

Моделирование контента — критичный этап. Ошибка на этом этапе стоит дорого. Типичная проблема: поле body типа rich text для всего. Через полгода контент-менеджер хочет вставить видео между абзацами, добавить pull quote с кастомным стилем, встроить интерактивную таблицу. Rich text это не позволяет. Решение — Portable Text (Sanity) или кастомные компоненты в Strapi/Directus через Dynamic Zone. Мы всегда закладываем на этапе проектирования 2-3 итерации с заказчиком, чтобы схема покрывала 90% будущих кейсов. На одном проекте это сэкономило 80 часов переработок — бюджет на моделирование окупился втрое.

Как мы строим проекты на headless CMS

Фронтенд под headless CMS практически всегда идёт на Next.js (App Router) или Nuxt. Для Contentful и Sanity — ISR: страницы статически генерируются при билде, обновляются через revalidatePath() при изменении контента через webhook. Для Strapi/Directus с частым обновлением данных — SSR с cache: 'no-store' или SWR на клиенте.

Кейс: редизайн корпоративного сайта производственной компании. Предыдущий сайт — WordPress с ACF, 200+ страниц, 4 языка. Проблемы: TTFB 3,8 с, редакторы жаловались на медленный админ.
Перешли на Strapi (self-hosted, PostgreSQL), Next.js App Router. Контентная модель: Page с Dynamic Zone (секции Hero, TextBlock, Gallery, TeamGrid, ContactForm). Локализация через Strapi i18n plugin + next-intl на фронтенде. Деплой фронтенда на Vercel с ISR, ревалидация через Strapi webhook на entry.publish.

TTFB с 3,8 с упал до 180 мс (статика с CDN) — разница в 21 раз. Редакторы получили чистый интерфейс без 47 плагинов. Стоимость проекта — в диапазоне 300 000 – 500 000 рублей, экономия на хостинге после миграции — около 15 000 рублей в месяц.

Для понимания headless CMS и TTFB — рекомендую базовые статьи.

Процесс внедрения разбит на этапы:

1. Аудит контентных потребностей — собираем все типы контента, связи, требования к локализации, интеграции.
2. Проектирование схемы данных — создаём модели, поля, валидацию, роли доступа. Документируем в Swagger/OpenAPI.
3. Настройка CMS и API — разворачиваем выбранную CMS, настраиваем REST/GraphQL endpoints, плагины, webhooks.
4. Разработка фронтенда — подключаем Next.js/Nuxt, настраиваем ISR/SSR, компоненты секций, роутинг.
5. Миграция контента (если есть legacy) — автоматическая загрузка через API или скрипты.
6. Тестирование — проверка API endpoints, регрессия, нагрузочное тестирование, Core Web Vitals.
7. Деплой — настройка CDN, SSL, CI/CD, мониторинг.

Сколько времени занимает внедрение?

Стандартный путь включает все этапы. Миграция с WordPress на headless CMS занимает столько же времени, сколько сам проект — часто больше. Особенно если в WordPress накоплены кастомные поля через ACF с нестандартной структурой. Наши средние сроки:

Стоимость рассчитывается индивидуально после брифа. Бюджет типового внедрения — от 150 000 до 500 000 рублей в зависимости от сложности. Экономия на хостинге за счёт статической генерации — до 40% в месяц.

Что входит в работу

• Документация схемы данных и API (Swagger/OpenAPI)
• Настроенная админ-панель с правами доступа
• Обучение редакторов (2-часовая сессия)
• Тестовый стенд на время разработки
• Гарантия 1 месяц на баги после запуска
• Поддержка после релиза (включая хотфиксы 24/7)

Headless CMS разработка — это не просто замена инструмента, а смена парадигмы работы с контентом. Мы помогаем сделать этот переход без простоев и потери данных. Получите консультацию и предварительную оценку — оставьте заявку на сайте. Закажите внедрение headless CMS с гарантией результата.