# Що таке плагін

Плагін — самостійний пакет, що розширює Celena, не змінюючи її ядро. Він може:

- додавати сторінки в адмінку та/або на фронт;
- реєструвати нові теги шаблонізатора та async-блоки;
- підписуватися на хуки ядра (`news.published`, `user.registered` тощо) і випускати власні;
- мати власні міграції, моделі та сервіси;
- розповсюджуватися через маркетплейс або вручну (zip).

Важливий принцип: **ядро самодостатнє**. Без плагіна все працює; плагін лише розширює через хуки і не модифікує ядро. Плагіни можна вмикати й вимикати в розділі **Плагіни** панелі керування.

## Структура

```
plugins/<slug>/
├── manifest.json     метадані (обовʼязково)
├── plugin.php        точка входу (обовʼязково)
├── README.md         рекомендовано
├── migrations/       міграції БД (необовʼязково)
├── src/              PHP-класи (PSR-4 Celena\Plugin\<Slug>\)
│   ├── Controllers/
│   ├── Admin/
│   ├── Repositories/
│   └── Support/
├── templates/        .tpl плагіна (адмінка і фронт)
├── languages/        ru.json, en.json тощо
├── assets/           CSS/JS → копіюються в public/assets/plugins/<slug>/
└── docs/             Markdown-документація плагіна
```

## manifest.json

```json
{
  "slug": "shop",
  "name": "Інтернет-магазин",
  "version": "1.0.0",
  "author": "Celena",
  "description": "Каталог, кошик, замовлення, платежі.",
  "requires": { "php": ">=8.3", "celena": ">=1.0", "plugins": [] },
  "permissions": ["news.read", "options.write"],
  "migrations": "migrations/"
}
```

Поле `slug` обовʼязкове і має відповідати `^[a-z0-9][a-z0-9_\-]*$`. Імʼя теки = `slug`.

## Як ядро знаходить і вантажить плагіни

1. `PluginManager::discover()` сканує `plugins/*`, читає кожен `manifest.json`.
2. Список активних плагінів зберігається в опції `active_plugins` (JSON-масив slug-ів у таблиці `cl_celena_options`).
3. Для активних плагінів `PluginManager::load()`:
   - реєструє простір імен `Celena\Plugin\<Slug>\` → `plugins/<slug>/src/`;
   - підключає `plugin.php` (тут реєструються маршрути, хуки, теги);
   - синхронізує `assets/` у `public/assets/plugins/<slug>/`.

Увімкнення/вимкнення плагіна = додавання/видалення його slug в `active_plugins` (через адмінку). При першому ввімкненні проганяються міграції.

## Еталонні плагіни

У комплекті є робочі плагіни — вивчайте їх як зразок:

- `plugins/leads/` — конструктор форм і приймання заявок (форми, honeypot, експорт, інʼєкція форми в лендинг). Гарний мінімальний приклад.
- `plugins/analytics/` — власна аналітика (трекер, події, цілі, дашборд).
- `plugins/shop/` — великий e-commerce (каталог, кошик, замовлення) — приклад великого плагіна.

Далі — [покрокове створення плагіна](/docs/code/plugin-create).
