# Что такое плагин

Плагин — самостоятельный пакет, расширяющий 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()`:
   - регистрирует namespace `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).
