# Архитектура

Celena — самописная PHP-CMS без сторонних фреймворков (без Laravel/Symfony) и без Composer-зависимостей в ядре. Весь код написан на чистом PHP 8.3+ с обязательным `declare(strict_types=1)` и строгой типизацией.

Если вы только начинаете — прочитайте эту страницу, затем [Структуру проекта](/docs/code/structure) и [Жизненный цикл запроса](/docs/code/lifecycle). Для разработки расширений переходите к разделу [Что такое плагин](/docs/code/plugins-intro).

## Точки входа

| Файл | Назначение |
|------|------------|
| `index.php` | Фронт сайта — все публичные запросы. |
| `admin.php` | Админ-панель (тонкий загрузчик, передаёт управление в `Kernel`). |
| `install.php` | Самоудаляющийся визард установки (после установки появляется `install.lock`). |
| `bin/celena` | CLI: миграции, плагины, очередь, кеш. |

Все запросы проходят через ядро `Celena\Core\Kernel`:

```
HTTP-запрос → index.php → core/bootstrap.php → Kernel::boot()
  → Autoloader → Container → Config → сервисы
  → Router::dispatch(Request) → Middleware → Controller → Response → send()
```

## Слои

Код разделён на четыре слоя со строгим направлением зависимостей:

| Слой | Папка | Зависит от |
|------|-------|------------|
| Ядро (без знаний о домене) | `core/` | только `core/*` |
| Встроенные модули CMS | `modules/` | `core/*` |
| Плагины (расширения) | `plugins/` | `core/*`, опц. другие плагины через манифест |
| Темы (оформление) | `templates/` | только теги шаблонизатора |

Ядро не знает про новости, магазин или формы — оно предоставляет инструменты (роутер, БД, шаблонизатор, хуки), а конкретную функциональность дают модули и плагины.

## Пространства имён и автозагрузка

PSR-4 через `core/Autoloader.php`. Маппинги:

- `Celena\Core\` → `core/`
- `Celena\Module\<Name>\` → `modules/<Name>/`
- `Celena\Plugin\<Slug>\` → `plugins/<slug>/src/`
- `Celena\Theme\<Slug>\` → `templates/<slug>/`

**Правило: один класс — один файл.** Имя файла совпадает с именем класса.

## Контракты

- Везде `declare(strict_types=1)`, типы аргументов и возврата обязательны.
- Любой пользовательский ввод проходит через `Celena\Core\Security\Filter`.
- Любой вывод в HTML — через `e()` (хелпер экранирования) или авто-экранирование шаблонизатора.
- Работа с БД — только через `QueryBuilder` или `PDO::prepare`. **Конкатенация значений в SQL запрещена.**

## Хуки (events)

Расширения общаются с ядром через систему хуков в стиле WordPress — actions (побочные эффекты) и filters (преобразование значения):

```php
use Celena\Core\Plugin\Hook;

Hook::action('news.published', $news);              // вызвать action
Hook::on('news.published', fn($n) => /* ... */);    // подписаться

$title = Hook::filter('news.title', $news['title']); // применить фильтры
Hook::addFilter('news.title', fn($t) => trim($t));   // подписаться на фильтр
```

Подробнее — на странице [Хуки и события](/docs/code/hooks).

## Кеш

- Кеш данных по умолчанию файловый (`storage/cache/data`); опционально APCu/Redis.
- Шаблоны компилируются в PHP и кешируются в `storage/cache/tpl/{hash}.php`. Инвалидация — по времени изменения исходника (mtime) и вручную.
