Справочник разработчика

Хуки и разработка плагинов

Расширяйте TubePress с помощью системы хуков действий и фильтров в стиле WordPress: более 15 точек подключения, жизненный цикл плагина и создание и упаковка собственного плагина.

Плагины — это способ добавлять функции в TubePress, не затрагивая ядро. Они интегрируются в CMS через небольшую систему в стиле WordPress: действия (события по принципу «выстрелил и забыл») и фильтры (изменяют значение и возвращают его). Три встроенных плагина — Age Gate, Backup Pro и CTR Ranking — построены целиком на том же API, который описан здесь.

Система хуков

Статический класс HookSystem управляет обоими типами хуков. Коллбэки выполняются в порядке возрастания приоритета (по умолчанию 10); любое исключение, брошенное коллбэком, перехватывается и логируется, поэтому один неисправный плагин никогда не обрушит страницу.

// Actions — do something when an event fires
HookSystem::addAction('head.meta', function () {
    echo '<meta name="rating" content="adult">';
}, 10);

// Filters — receive a value, return a (possibly) changed value
HookSystem::addFilter('theme.template_data', function ($data, $template) {
    if ($template === 'home') {
        $data['promo'] = Promo::current();
    }
    return $data;
});

Метод	Назначение
`addAction($hook, $cb, $priority = 10)`	Зарегистрировать слушателя действия.
`doAction($hook, ...$args)`	Запустить действие (вызывается ядром).
`addFilter($hook, $cb, $priority = 10)`	Зарегистрировать фильтр.
`applyFilter($hook, $value, ...$args)`	Пропустить значение через фильтры и вернуть его.
`hasAction()` / `hasFilter()`	Проверить наличие слушателей.
`removeAction()` / `removeFilter()`	Отсоединить всех слушателей хука.

Доступные точки хуков

Ядро запускает эти хуки. Вы также можете определять и запускать собственные хуки из плагина.

Действия

Хук	Когда срабатывает
`head.meta`	Внутри `<head>`, после CSS — добавить мета-теги, теги верификации и т. д.
`footer.scripts`	Перед `</body>`, после JS — добавить аналитику или виджеты.
`routes.registered`	После регистрации всех маршрутов ядра, перед перехватчиком страниц.
`router.before_dispatch`	Непосредственно перед выполнением найденного обработчика. Аргумент: разрешённый путь.

Фильтры

Хук	Изменяет (аргументы)
`theme.template_data`	Массив данных перед рендерингом шаблона. Аргументы: `($data, $templateName)`.
`head.css`	Объединённая строка вывода CSS.
`footer.scripts`	Объединённая строка вывода JS.
`video.card.html`	Весь HTML карточки видео. Аргументы: `($html, $video)`. Верните непустую строку, чтобы заменить его.

Анатомия плагина

Плагин — это папка в plugins/ с манифестом и классом, реализующим PluginInterface.

plugins/myplugin/
├── plugin.json     Manifest (name, slug, version, …)
├── myplugin.php    Main class implementing PluginInterface
├── icon.svg        Optional icon shown in the admin
└── …               Your assets, templates, migrations

Манифест повторяет структуру встроенных плагинов:

{
  "name": "My Plugin",
  "slug": "myplugin",
  "description": "What it does, in one sentence.",
  "version": "1.0.0",
  "author": "You",
  "requires": "1.0.0",
  "icon": "icon.svg"
}

Основной класс реализует шесть методов жизненного цикла PluginInterface:

Метод	Когда вызывается
`boot()`	При каждом запросе, пока плагин активен — регистрируйте здесь хуки, маршруты и ресурсы.
`activate()`	Администратор включает плагин.
`deactivate()`	Администратор отключает его.
`install()`	Первая активация — создать таблицы, заполнить настройки.
`uninstall()`	Плагин удаляется — очистить за собой.
`info()`	Возвращает данные манифеста в виде массива.

Регистрация маршрутов & ресурсов

Всю инициализацию выполняйте в boot():

public function boot(): void
{
    // A front-end route
    Router::get('/promo/{code}', [PromoController::class, 'show']);

    // Inject a meta tag
    HookSystem::addAction('head.meta', [$this, 'meta']);

    // Tweak every video card
    HookSystem::addFilter('video.card.html', [$this, 'badge'], 20);
}

Самодостаточность по концепции. Плагин должен добавлять всё необходимое — собственную схему, настройки, маршруты, страницы администратора и запланированные задачи — и удалять их при деинсталляции, не изменяя базовый CMS. Плагин CTR Ranking служит хорошим примером.

Плановые задачи в плагине

Зарегистрируйте периодическую задачу с помощью CronManager в boot() — он работает на встроенном псевдо-cron, поэтому системный crontab не требуется. Именно так плагин CTR пересчитывает оценки, а Backup Pro выполняет плановые резервные копии.

Встроенные плагины как образцы

Age GateОверлей, мета-тег RTA, хранение в cookie. Backup ProПрофили, удалённое хранилище, планирование. CTR RankingОтслеживание, cron пересчёта, подключение сортировки.

Распространение & лицензирование

Вы можете оставить плагин приватным, распространять его бесплатно или продавать через маркетплейс, который добавляет подписанное лицензирование и активацию по домену. Для аналогичной функциональности на стороне представления смотрите разработку тем, а для всего доступного коду шаблонов — справочник Theme API.

Остались вопросы?

Откройте заявку в панели управления, и наша команда поможет.

Попробовать демо → Скачать TubePress →